MDL-71706 libraries: upgrade to version 1.10.0 of ScssPhp.

lib/scssphp/Base/Range.php

@@ -16,17 +16,26 @@ namespace ScssPhp\ScssPhp\Base;
  * Range
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class Range
 {
+    /**
+     * @var float|int
+     */
     public $first;
+
+    /**
+     * @var float|int
+     */
     public $last;
 
     /**
      * Initialize range
      *
-     * @param integer|float $first
+     * @param int|float $first
-     * @param integer|float $last
+     * @param int|float $last
      */
     public function __construct($first, $last)
     {
@@ -37,9 +46,9 @@ class Range
     /**
      * Test for inclusion in range
      *
-     * @param integer|float $value
+     * @param int|float $value
      *
-     * @return boolean
+     * @return bool
      */
     public function includes($value)
     {

lib/scssphp/Block.php

@@ -16,16 +16,18 @@ namespace ScssPhp\ScssPhp;
  * Block
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class Block
 {
     /**
-     * @var string
+     * @var string|null
      */
     public $type;
 
     /**
-     * @var \ScssPhp\ScssPhp\Block
+     * @var Block|null
      */
     public $parent;
 
@@ -35,17 +37,17 @@ class Block
     public $sourceName;
 
     /**
-     * @var integer
+     * @var int
      */
     public $sourceIndex;
 
     /**
-     * @var integer
+     * @var int
      */
     public $sourceLine;
 
     /**
-     * @var integer
+     * @var int
      */
     public $sourceColumn;
 
@@ -65,7 +67,7 @@ class Block
     public $children;
 
     /**
-     * @var \ScssPhp\ScssPhp\Block
+     * @var Block|null
      */
     public $selfParent;
 }

lib/scssphp/Block/AtRootBlock.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class AtRootBlock extends Block
+{
+    /**
+     * @var array|null
+     */
+    public $selector;
+
+    /**
+     * @var array|null
+     */
+    public $with;
+
+    public function __construct()
+    {
+        $this->type = Type::T_AT_ROOT;
+    }
+}

lib/scssphp/Block/CallableBlock.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Compiler\Environment;
+
+/**
+ * @internal
+ */
+class CallableBlock extends Block
+{
+    /**
+     * @var string
+     */
+    public $name;
+
+    /**
+     * @var array|null
+     */
+    public $args;
+
+    /**
+     * @var Environment|null
+     */
+    public $parentEnv;
+
+    /**
+     * @param string $type
+     */
+    public function __construct($type)
+    {
+        $this->type = $type;
+    }
+}

lib/scssphp/Block/ContentBlock.php

@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Compiler\Environment;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class ContentBlock extends Block
+{
+    /**
+     * @var array|null
+     */
+    public $child;
+
+    /**
+     * @var Environment|null
+     */
+    public $scope;
+
+    public function __construct()
+    {
+        $this->type = Type::T_INCLUDE;
+    }
+}

lib/scssphp/Block/DirectiveBlock.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class DirectiveBlock extends Block
+{
+    /**
+     * @var string|array
+     */
+    public $name;
+
+    /**
+     * @var string|array|null
+     */
+    public $value;
+
+    public function __construct()
+    {
+        $this->type = Type::T_DIRECTIVE;
+    }
+}

lib/scssphp/Block/EachBlock.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class EachBlock extends Block
+{
+    /**
+     * @var string[]
+     */
+    public $vars = [];
+
+    /**
+     * @var array
+     */
+    public $list;
+
+    public function __construct()
+    {
+        $this->type = Type::T_EACH;
+    }
+}

lib/scssphp/Block/ElseBlock.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class ElseBlock extends Block
+{
+    public function __construct()
+    {
+        $this->type = Type::T_ELSE;
+    }
+}

lib/scssphp/Block/ElseifBlock.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class ElseifBlock extends Block
+{
+    /**
+     * @var array
+     */
+    public $cond;
+
+    public function __construct()
+    {
+        $this->type = Type::T_ELSEIF;
+    }
+}

lib/scssphp/Block/ForBlock.php

@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class ForBlock extends Block
+{
+    /**
+     * @var string
+     */
+    public $var;
+
+    /**
+     * @var array
+     */
+    public $start;
+
+    /**
+     * @var array
+     */
+    public $end;
+
+    /**
+     * @var bool
+     */
+    public $until;
+
+    public function __construct()
+    {
+        $this->type = Type::T_FOR;
+    }
+}

lib/scssphp/Block/IfBlock.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class IfBlock extends Block
+{
+    /**
+     * @var array
+     */
+    public $cond;
+
+    /**
+     * @var array<ElseifBlock|ElseBlock>
+     */
+    public $cases = [];
+
+    public function __construct()
+    {
+        $this->type = Type::T_IF;
+    }
+}

lib/scssphp/Block/MediaBlock.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class MediaBlock extends Block
+{
+    /**
+     * @var string|array|null
+     */
+    public $value;
+
+    /**
+     * @var array|null
+     */
+    public $queryList;
+
+    public function __construct()
+    {
+        $this->type = Type::T_MEDIA;
+    }
+}

lib/scssphp/Block/NestedPropertyBlock.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class NestedPropertyBlock extends Block
+{
+    /**
+     * @var bool
+     */
+    public $hasValue;
+
+    /**
+     * @var array
+     */
+    public $prefix;
+
+    public function __construct()
+    {
+        $this->type = Type::T_NESTED_PROPERTY;
+    }
+}

lib/scssphp/Block/WhileBlock.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Block;
+
+use ScssPhp\ScssPhp\Block;
+use ScssPhp\ScssPhp\Type;
+
+/**
+ * @internal
+ */
+class WhileBlock extends Block
+{
+    /**
+     * @var array
+     */
+    public $cond;
+
+    public function __construct()
+    {
+        $this->type = Type::T_WHILE;
+    }
+}

lib/scssphp/Cache.php

@@ -30,30 +30,54 @@ use ScssPhp\ScssPhp\Version;
  * SCSS cache
  *
  * @author Cedric Morin <cedric@yterium.com>
+ *
+ * @internal
  */
 class Cache
 {
     const CACHE_VERSION = 1;
 
-    // directory used for storing data
+    /**
+     * directory used for storing data
+     *
+     * @var string|false
+     */
     public static $cacheDir = false;
 
-    // prefix for the storing data
+    /**
+     * prefix for the storing data
+     *
+     * @var string
+     */
     public static $prefix = 'scssphp_';
 
-    // force a refresh : 'once' for refreshing the first hit on a cache only, true to never use the cache in this hit
+    /**
+     * force a refresh : 'once' for refreshing the first hit on a cache only, true to never use the cache in this hit
+     *
+     * @var bool|string
+     */
     public static $forceRefresh = false;
 
-    // specifies the number of seconds after which data cached will be seen as 'garbage' and potentially cleaned up
+    /**
+     * specifies the number of seconds after which data cached will be seen as 'garbage' and potentially cleaned up
+     *
+     * @var int
+     */
     public static $gcLifetime = 604800;
 
-    // array of already refreshed cache if $forceRefresh==='once'
+    /**
+     * array of already refreshed cache if $forceRefresh==='once'
+     *
+     * @var array<string, bool>
+     */
     protected static $refreshed = [];
 
     /**
      * Constructor
      *
      * @param array $options
+     *
+     * @phpstan-param array{cacheDir?: string, prefix?: string, forceRefresh?: string} $options
      */
     public function __construct($options)
     {
@@ -85,10 +109,10 @@ class Cache
      * Get the cached result of $operation on $what,
      * which is known as dependant from the content of $options
      *
-     * @param string  $operation    parse, compile...
+     * @param string   $operation    parse, compile...
-     * @param mixed   $what         content key (e.g., filename to be treated)
+     * @param mixed    $what         content key (e.g., filename to be treated)
-     * @param array   $options      any option that affect the operation result on the content
+     * @param array    $options      any option that affect the operation result on the content
-     * @param integer $lastModified last modified timestamp
+     * @param int|null $lastModified last modified timestamp
      *
      * @return mixed
      *
@@ -128,6 +152,8 @@ class Cache
      * @param mixed  $what
      * @param mixed  $value
      * @param array  $options
+     *
+     * @return void
      */
     public function setCache($operation, $what, $value, $options = [])
     {
@@ -174,6 +200,8 @@ class Cache
     /**
      * Check that the cache dir exists and is writeable
      *
+     * @return void
+     *
      * @throws \Exception
      */
     public static function checkCacheDir()
@@ -192,6 +220,8 @@ class Cache
 
     /**
      * Delete unused cached files
+     *
+     * @return void
      */
     public static function cleanCache()
     {

lib/scssphp/Colors.php

@@ -16,6 +16,8 @@ namespace ScssPhp\ScssPhp;
  * CSS Colors
  *
  * @author Leaf Corcoran <leafot@gmail.com>
+ *
+ * @internal
  */
 class Colors
 {
@@ -24,13 +26,13 @@ class Colors
      *
      * @see http://www.w3.org/TR/css3-color
      *
-     * @var array
+     * @var array<string, string>
      */
     protected static $cssColors = [
         'aliceblue' => '240,248,255',
         'antiquewhite' => '250,235,215',
-        'cyan' => '0,255,255',
         'aqua' => '0,255,255',
+        'cyan' => '0,255,255',
         'aquamarine' => '127,255,212',
         'azure' => '240,255,255',
         'beige' => '245,245,220',
@@ -75,8 +77,8 @@ class Colors
         'firebrick' => '178,34,34',
         'floralwhite' => '255,250,240',
         'forestgreen' => '34,139,34',
-        'magenta' => '255,0,255',
         'fuchsia' => '255,0,255',
+        'magenta' => '255,0,255',
         'gainsboro' => '220,220,220',
         'ghostwhite' => '248,248,255',
         'gold' => '255,215,0',
@@ -183,7 +185,7 @@ class Colors
      *
      * @param string $colorName
      *
-     * @return array|null
+     * @return int[]|null
      */
     public static function colorNameToRGBa($colorName)
     {
@@ -202,10 +204,10 @@ class Colors
     /**
      * Reverse conversion : from RGBA to a color name if possible
      *
-     * @param integer $r
+     * @param int       $r
-     * @param integer $g
+     * @param int       $g
-     * @param integer $b
+     * @param int       $b
-     * @param integer $a
+     * @param int|float $a
      *
      * @return string|null
      */

lib/scssphp/CompilationResult.php

@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp;
+
+class CompilationResult
+{
+    /**
+     * @var string
+     */
+    private $css;
+
+    /**
+     * @var string|null
+     */
+    private $sourceMap;
+
+    /**
+     * @var string[]
+     */
+    private $includedFiles;
+
+    /**
+     * @param string $css
+     * @param string|null $sourceMap
+     * @param string[] $includedFiles
+     */
+    public function __construct($css, $sourceMap, array $includedFiles)
+    {
+        $this->css = $css;
+        $this->sourceMap = $sourceMap;
+        $this->includedFiles = $includedFiles;
+    }
+
+    /**
+     * @return string
+     */
+    public function getCss()
+    {
+        return $this->css;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getIncludedFiles()
+    {
+        return $this->includedFiles;
+    }
+
+    /**
+     * The sourceMap content, if it was generated
+     *
+     * @return null|string
+     */
+    public function getSourceMap()
+    {
+        return $this->sourceMap;
+    }
+}

lib/scssphp/Compiler/CachedResult.php

@@ -0,0 +1,77 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Compiler;
+
+use ScssPhp\ScssPhp\CompilationResult;
+
+/**
+ * @internal
+ */
+class CachedResult
+{
+    /**
+     * @var CompilationResult
+     */
+    private $result;
+
+    /**
+     * @var array<string, int>
+     */
+    private $parsedFiles;
+
+    /**
+     * @var array
+     * @phpstan-var list<array{currentDir: string|null, path: string, filePath: string}>
+     */
+    private $resolvedImports;
+
+    /**
+     * @param CompilationResult  $result
+     * @param array<string, int> $parsedFiles
+     * @param array              $resolvedImports
+     *
+     * @phpstan-param list<array{currentDir: string|null, path: string, filePath: string}> $resolvedImports
+     */
+    public function __construct(CompilationResult $result, array $parsedFiles, array $resolvedImports)
+    {
+        $this->result = $result;
+        $this->parsedFiles = $parsedFiles;
+        $this->resolvedImports = $resolvedImports;
+    }
+
+    /**
+     * @return CompilationResult
+     */
+    public function getResult()
+    {
+        return $this->result;
+    }
+
+    /**
+     * @return array<string, int>
+     */
+    public function getParsedFiles()
+    {
+        return $this->parsedFiles;
+    }
+
+    /**
+     * @return array
+     *
+     * @phpstan-return list<array{currentDir: string|null, path: string, filePath: string}>
+     */
+    public function getResolvedImports()
+    {
+        return $this->resolvedImports;
+    }
+}

lib/scssphp/Compiler/Environment.php

@@ -16,19 +16,41 @@ namespace ScssPhp\ScssPhp\Compiler;
  * Compiler environment
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class Environment
 {
     /**
-     * @var \ScssPhp\ScssPhp\Block
+     * @var \ScssPhp\ScssPhp\Block|null
      */
     public $block;
 
     /**
-     * @var \ScssPhp\ScssPhp\Compiler\Environment
+     * @var \ScssPhp\ScssPhp\Compiler\Environment|null
      */
     public $parent;
 
+    /**
+     * @var Environment|null
+     */
+    public $declarationScopeParent;
+
+    /**
+     * @var Environment|null
+     */
+    public $parentStore;
+
+    /**
+     * @var array|null
+     */
+    public $selectors;
+
+    /**
+     * @var string|null
+     */
+    public $marker;
+
     /**
      * @var array
      */
@@ -40,7 +62,7 @@ class Environment
     public $storeUnreduced;
 
     /**
-     * @var integer
+     * @var int
      */
     public $depth;
 }

lib/scssphp/Exception/CompilerException.php

@@ -16,6 +16,8 @@ namespace ScssPhp\ScssPhp\Exception;
  * Compiler exception
  *
  * @author Oleksandr Savchenko <traveltino@gmail.com>
+ *
+ * @internal
  */
 class CompilerException extends \Exception implements SassException
 {

lib/scssphp/Exception/ParserException.php

@@ -16,6 +16,8 @@ namespace ScssPhp\ScssPhp\Exception;
  * Parser Exception
  *
  * @author Oleksandr Savchenko <traveltino@gmail.com>
+ *
+ * @internal
  */
 class ParserException extends \Exception implements SassException
 {

lib/scssphp/Exception/RangeException.php

@@ -16,6 +16,8 @@ namespace ScssPhp\ScssPhp\Exception;
  * Range exception
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class RangeException extends \Exception implements SassException
 {

lib/scssphp/Exception/ServerException.php

@@ -12,10 +12,14 @@
 
 namespace ScssPhp\ScssPhp\Exception;
 
+@trigger_error(sprintf('The "%s" class is deprecated.', ServerException::class), E_USER_DEPRECATED);
+
 /**
  * Server Exception
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @deprecated The Scssphp server should define its own exception instead.
  */
 class ServerException extends \Exception implements SassException
 {

lib/scssphp/Formatter.php

@@ -19,11 +19,13 @@ use ScssPhp\ScssPhp\SourceMap\SourceMapGenerator;
  * Base formatter
  *
  * @author Leaf Corcoran <leafot@gmail.com>
+ *
+ * @internal
  */
 abstract class Formatter
 {
     /**
-     * @var integer
+     * @var int
      */
     public $indentLevel;
 
@@ -58,7 +60,7 @@ abstract class Formatter
     public $assignSeparator;
 
     /**
-     * @var boolean
+     * @var bool
      */
     public $keepSemicolons;
 
@@ -68,17 +70,17 @@ abstract class Formatter
     protected $currentBlock;
 
     /**
-     * @var integer
+     * @var int
      */
     protected $currentLine;
 
     /**
-     * @var integer
+     * @var int
      */
     protected $currentColumn;
 
     /**
-     * @var \ScssPhp\ScssPhp\SourceMap\SourceMapGenerator
+     * @var \ScssPhp\ScssPhp\SourceMap\SourceMapGenerator|null
      */
     protected $sourceMapGenerator;
 
@@ -139,6 +141,8 @@ abstract class Formatter
      * Output lines inside a block
      *
      * @param \ScssPhp\ScssPhp\Formatter\OutputBlock $block
+     *
+     * @return void
      */
     protected function blockLines(OutputBlock $block)
     {
@@ -156,9 +160,13 @@ abstract class Formatter
      * Output block selectors
      *
      * @param \ScssPhp\ScssPhp\Formatter\OutputBlock $block
+     *
+     * @return void
      */
     protected function blockSelectors(OutputBlock $block)
     {
+        assert(! empty($block->selectors));
+
         $inner = $this->indentStr();
 
         $this->write($inner
@@ -170,6 +178,8 @@ abstract class Formatter
      * Output block children
      *
      * @param \ScssPhp\ScssPhp\Formatter\OutputBlock $block
+     *
+     * @return void
      */
     protected function blockChildren(OutputBlock $block)
     {
@@ -182,6 +192,8 @@ abstract class Formatter
      * Output non-empty block
      *
      * @param \ScssPhp\ScssPhp\Formatter\OutputBlock $block
+     *
+     * @return void
      */
     protected function block(OutputBlock $block)
     {
@@ -227,7 +239,7 @@ abstract class Formatter
      *
      * @param \ScssPhp\ScssPhp\Formatter\OutputBlock $block
      *
-     * @return boolean
+     * @return bool
      */
     protected function testEmptyChildren($block)
     {
@@ -285,6 +297,8 @@ abstract class Formatter
      * Output content
      *
      * @param string $str
+     *
+     * @return void
      */
     protected function write($str)
     {

lib/scssphp/Formatter/Compact.php

@@ -20,6 +20,8 @@ use ScssPhp\ScssPhp\Formatter;
  * @author Leaf Corcoran <leafot@gmail.com>
  *
  * @deprecated since 1.4.0. Use the Compressed formatter instead.
+ *
+ * @internal
  */
 class Compact extends Formatter
 {

lib/scssphp/Formatter/Compressed.php

@@ -18,6 +18,8 @@ use ScssPhp\ScssPhp\Formatter;
  * Compressed formatter
  *
  * @author Leaf Corcoran <leafot@gmail.com>
+ *
+ * @internal
  */
 class Compressed extends Formatter
 {
@@ -48,8 +50,6 @@ class Compressed extends Formatter
         foreach ($block->lines as $index => $line) {
             if (substr($line, 0, 2) === '/*' && substr($line, 2, 1) !== '!') {
                 unset($block->lines[$index]);
-            } elseif (substr($line, 0, 3) === '/*!') {
-                $block->lines[$index] = '/*' . substr($line, 3);
             }
         }
 
@@ -67,6 +67,8 @@ class Compressed extends Formatter
      */
     protected function blockSelectors(OutputBlock $block)
     {
+        assert(! empty($block->selectors));
+
         $inner = $this->indentStr();
 
         $this->write(

lib/scssphp/Formatter/Crunched.php

@@ -20,6 +20,8 @@ use ScssPhp\ScssPhp\Formatter;
  * @author Anthon Pang <anthon.pang@gmail.com>
  *
  * @deprecated since 1.4.0. Use the Compressed formatter instead.
+ *
+ * @internal
  */
 class Crunched extends Formatter
 {
@@ -69,6 +71,8 @@ class Crunched extends Formatter
      */
     protected function blockSelectors(OutputBlock $block)
     {
+        assert(! empty($block->selectors));
+
         $inner = $this->indentStr();
 
         $this->write(

lib/scssphp/Formatter/Debug.php

@@ -20,6 +20,8 @@ use ScssPhp\ScssPhp\Formatter;
  * @author Anthon Pang <anthon.pang@gmail.com>
  *
  * @deprecated since 1.4.0.
+ *
+ * @internal
  */
 class Debug extends Formatter
 {

lib/scssphp/Formatter/Expanded.php

@@ -18,6 +18,8 @@ use ScssPhp\ScssPhp\Formatter;
  * Expanded formatter
  *
  * @author Leaf Corcoran <leafot@gmail.com>
+ *
+ * @internal
  */
 class Expanded extends Formatter
 {

lib/scssphp/Formatter/Nested.php

@@ -21,11 +21,13 @@ use ScssPhp\ScssPhp\Type;
  * @author Leaf Corcoran <leafot@gmail.com>
  *
  * @deprecated since 1.4.0. Use the Expanded formatter instead.
+ *
+ * @internal
  */
 class Nested extends Formatter
 {
     /**
-     * @var integer
+     * @var int
      */
     private $depth;
 
@@ -219,7 +221,7 @@ class Nested extends Formatter
      *
      * @param \ScssPhp\ScssPhp\Formatter\OutputBlock $block
      *
-     * @return boolean
+     * @return bool
      */
     private function hasFlatChild($block)
     {

lib/scssphp/Formatter/OutputBlock.php

@@ -16,6 +16,8 @@ namespace ScssPhp\ScssPhp\Formatter;
  * Output block
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class OutputBlock
 {
@@ -25,22 +27,22 @@ class OutputBlock
     public $type;
 
     /**
-     * @var integer
+     * @var int
      */
     public $depth;
 
     /**
-     * @var array
+     * @var array|null
      */
     public $selectors;
 
     /**
-     * @var array
+     * @var string[]
      */
     public $lines;
 
     /**
-     * @var array
+     * @var OutputBlock[]
      */
     public $children;
 
@@ -50,17 +52,17 @@ class OutputBlock
     public $parent;
 
     /**
-     * @var string
+     * @var string|null
      */
     public $sourceName;
 
     /**
-     * @var integer
+     * @var int|null
      */
     public $sourceLine;
 
     /**
-     * @var integer
+     * @var int|null
      */
     public $sourceColumn;
 }

lib/scssphp/Logger/LoggerInterface.php

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Logger;
+
+/**
+ * Interface implemented by loggers for warnings and debug messages.
+ *
+ * The official Sass implementation recommends that loggers report the
+ * messages immediately rather than waiting for the end of the
+ * compilation, to provide a better debugging experience when the
+ * compilation does not end (error or infinite loop after the warning
+ * for instance).
+ */
+interface LoggerInterface
+{
+    /**
+     * Emits a warning with the given message.
+     *
+     * If $deprecation is true, it indicates that this is a deprecation
+     * warning. Implementations should surface all this information to
+     * the end user.
+     *
+     * @param string $message
+     * @param bool  $deprecation
+     *
+     * @return void
+     */
+    public function warn($message, $deprecation = false);
+
+    /**
+     * Emits a debugging message.
+     *
+     * @param string $message
+     *
+     * @return void
+     */
+    public function debug($message);
+}

lib/scssphp/Logger/QuietLogger.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Logger;
+
+/**
+ * A logger that silently ignores all messages.
+ */
+class QuietLogger implements LoggerInterface
+{
+    public function warn($message, $deprecation = false)
+    {
+    }
+
+    public function debug($message)
+    {
+    }
+}

lib/scssphp/Logger/StreamLogger.php

@@ -0,0 +1,60 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp\Logger;
+
+/**
+ * A logger that prints to a PHP stream (for instance stderr)
+ */
+class StreamLogger implements LoggerInterface
+{
+    private $stream;
+    private $closeOnDestruct;
+
+    /**
+     * @param resource $stream          A stream resource
+     * @param bool     $closeOnDestruct If true, takes ownership of the stream and close it on destruct to avoid leaks.
+     */
+    public function __construct($stream, $closeOnDestruct = false)
+    {
+        $this->stream = $stream;
+        $this->closeOnDestruct = $closeOnDestruct;
+    }
+
+    /**
+     * @internal
+     */
+    public function __destruct()
+    {
+        if ($this->closeOnDestruct) {
+            fclose($this->stream);
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function warn($message, $deprecation = false)
+    {
+        $prefix = ($deprecation ? 'DEPRECATION ' : '') . 'WARNING: ';
+
+        fwrite($this->stream, $prefix . $message . "\n\n");
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function debug($message)
+    {
+        fwrite($this->stream, $message . "\n");
+    }
+}

lib/scssphp/Node.php

@@ -16,6 +16,8 @@ namespace ScssPhp\ScssPhp;
  * Base node
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 abstract class Node
 {
@@ -25,17 +27,17 @@ abstract class Node
     public $type;
 
     /**
-     * @var integer
+     * @var int
      */
     public $sourceIndex;
 
     /**
-     * @var integer
+     * @var int|null
      */
     public $sourceLine;
 
     /**
-     * @var integer
+     * @var int|null
      */
     public $sourceColumn;
 }

lib/scssphp/Node/Number.php

@@ -12,10 +12,13 @@
 
 namespace ScssPhp\ScssPhp\Node;
 
+use ScssPhp\ScssPhp\Base\Range;
 use ScssPhp\ScssPhp\Compiler;
+use ScssPhp\ScssPhp\Exception\RangeException;
 use ScssPhp\ScssPhp\Exception\SassScriptException;
 use ScssPhp\ScssPhp\Node;
 use ScssPhp\ScssPhp\Type;
+use ScssPhp\ScssPhp\Util;
 
 /**
  * Dimension + optional units
@@ -27,13 +30,15 @@ use ScssPhp\ScssPhp\Type;
  * }}
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @template-implements \ArrayAccess<int, mixed>
  */
 class Number extends Node implements \ArrayAccess
 {
     const PRECISION = 10;
 
     /**
-     * @var integer
+     * @var int
      * @deprecated use {Number::PRECISION} instead to read the precision. Configuring it is not supported anymore.
      */
     public static $precision = self::PRECISION;
@@ -42,6 +47,7 @@ class Number extends Node implements \ArrayAccess
      * @see http://www.w3.org/TR/2012/WD-css3-values-20120308/
      *
      * @var array
+     * @phpstan-var array<string, array<string, float|int>>
      */
     protected static $unitTable = [
         'in' => [
@@ -75,7 +81,7 @@ class Number extends Node implements \ArrayAccess
     ];
 
     /**
-     * @var integer|float
+     * @var int|float
      */
     private $dimension;
 
@@ -94,7 +100,7 @@ class Number extends Node implements \ArrayAccess
     /**
      * Initialize number
      *
-     * @param integer|float   $dimension
+     * @param int|float       $dimension
      * @param string[]|string $numeratorUnits
      * @param string[]        $denominatorUnits
      *
@@ -141,8 +147,9 @@ class Number extends Node implements \ArrayAccess
     }
 
     /**
-     * {@inheritdoc}
+     * @return bool
      */
+    #[\ReturnTypeWillChange]
     public function offsetExists($offset)
     {
         if ($offset === -3) {
@@ -166,8 +173,9 @@ class Number extends Node implements \ArrayAccess
     }
 
     /**
-     * {@inheritdoc}
+     * @return mixed
      */
+    #[\ReturnTypeWillChange]
     public function offsetGet($offset)
     {
         switch ($offset) {
@@ -192,16 +200,18 @@ class Number extends Node implements \ArrayAccess
     }
 
     /**
-     * {@inheritdoc}
+     * @return void
      */
+    #[\ReturnTypeWillChange]
     public function offsetSet($offset, $value)
     {
         throw new \BadMethodCallException('Number is immutable');
     }
 
     /**
-     * {@inheritdoc}
+     * @return void
      */
+    #[\ReturnTypeWillChange]
     public function offsetUnset($offset)
     {
         throw new \BadMethodCallException('Number is immutable');
@@ -210,7 +220,7 @@ class Number extends Node implements \ArrayAccess
     /**
      * Returns true if the number is unitless
      *
-     * @return boolean
+     * @return bool
      */
     public function unitless()
     {
@@ -243,6 +253,23 @@ class Number extends Node implements \ArrayAccess
         return self::getUnitString($this->numeratorUnits, $this->denominatorUnits);
     }
 
+    /**
+     * @param float|int $min
+     * @param float|int $max
+     * @param string|null $name
+     *
+     * @return float|int
+     * @throws SassScriptException
+     */
+    public function valueInRange($min, $max, $name = null)
+    {
+        try {
+            return Util::checkRange('', new Range($min, $max), $this);
+        } catch (RangeException $e) {
+            throw SassScriptException::forArgument(sprintf('Expected %s to be within %s%s and %s%3$s', $this, $min, $this->unitStr(), $max), $name);
+        }
+    }
+
     /**
      * @param string|null $varName
      *
@@ -254,7 +281,22 @@ class Number extends Node implements \ArrayAccess
             return;
         }
 
-        throw SassScriptException::forArgument(sprintf('Expected %s to have no units', $this), $varName);
+        throw SassScriptException::forArgument(sprintf('Expected %s to have no units.', $this), $varName);
+    }
+
+    /**
+     * @param string      $unit
+     * @param string|null $varName
+     *
+     * @return void
+     */
+    public function assertUnit($unit, $varName = null)
+    {
+        if ($this->hasUnit($unit)) {
+            return;
+        }
+
+        throw SassScriptException::forArgument(sprintf('Expected %s to have unit "%s".', $this, $unit), $varName);
     }
 
     /**
@@ -279,6 +321,29 @@ class Number extends Node implements \ArrayAccess
         ));
     }
 
+    /**
+     * Returns a copy of this number, converted to the units represented by $newNumeratorUnits and $newDenominatorUnits.
+     *
+     * This does not throw an error if this number is unitless and
+     * $newNumeratorUnits/$newDenominatorUnits are not empty, or vice versa. Instead,
+     * it treats all unitless numbers as convertible to and from all units without
+     * changing the value.
+     *
+     * @param string[] $newNumeratorUnits
+     * @param string[] $newDenominatorUnits
+     *
+     * @return Number
+     *
+     * @phpstan-param list<string> $newNumeratorUnits
+     * @phpstan-param list<string> $newDenominatorUnits
+     *
+     * @throws SassScriptException if this number's units are not compatible with $newNumeratorUnits and $newDenominatorUnits
+     */
+    public function coerce(array $newNumeratorUnits, array $newDenominatorUnits)
+    {
+        return new Number($this->valueInUnits($newNumeratorUnits, $newDenominatorUnits), $newNumeratorUnits, $newDenominatorUnits);
+    }
+
     /**
      * @param Number $other
      *
@@ -560,6 +625,8 @@ class Number extends Node implements \ArrayAccess
      *
      * @phpstan-param list<string> $numeratorUnits
      * @phpstan-param list<string> $denominatorUnits
+     *
+     * @throws SassScriptException if this number's units are not compatible with $numeratorUnits and $denominatorUnits
      */
     private function valueInUnits(array $numeratorUnits, array $denominatorUnits)
     {

lib/scssphp/Parser.php

@@ -12,12 +12,28 @@
 
 namespace ScssPhp\ScssPhp;
 
+use ScssPhp\ScssPhp\Block\AtRootBlock;
+use ScssPhp\ScssPhp\Block\CallableBlock;
+use ScssPhp\ScssPhp\Block\ContentBlock;
+use ScssPhp\ScssPhp\Block\DirectiveBlock;
+use ScssPhp\ScssPhp\Block\EachBlock;
+use ScssPhp\ScssPhp\Block\ElseBlock;
+use ScssPhp\ScssPhp\Block\ElseifBlock;
+use ScssPhp\ScssPhp\Block\ForBlock;
+use ScssPhp\ScssPhp\Block\IfBlock;
+use ScssPhp\ScssPhp\Block\MediaBlock;
+use ScssPhp\ScssPhp\Block\NestedPropertyBlock;
+use ScssPhp\ScssPhp\Block\WhileBlock;
 use ScssPhp\ScssPhp\Exception\ParserException;
+use ScssPhp\ScssPhp\Logger\LoggerInterface;
+use ScssPhp\ScssPhp\Logger\QuietLogger;
 
 /**
  * Parser
  *
  * @author Leaf Corcoran <leafot@gmail.com>
+ *
+ * @internal
  */
 class Parser
 {
@@ -80,7 +96,7 @@ class Parser
      */
     private $count;
     /**
-     * @var Block
+     * @var Block|null
      */
     private $env;
     /**
@@ -110,18 +126,24 @@ class Parser
 
     private $cssOnly;
 
+    /**
+     * @var LoggerInterface
+     */
+    private $logger;
+
     /**
      * Constructor
      *
      * @api
      *
-     * @param string      $sourceName
+     * @param string|null          $sourceName
-     * @param integer     $sourceIndex
+     * @param int                  $sourceIndex
-     * @param string|null $encoding
+     * @param string|null          $encoding
-     * @param Cache|null  $cache
+     * @param Cache|null           $cache
-     * @param bool        $cssOnly
+     * @param bool                 $cssOnly
+     * @param LoggerInterface|null $logger
      */
-    public function __construct($sourceName, $sourceIndex = 0, $encoding = 'utf-8', Cache $cache = null, $cssOnly = false)
+    public function __construct($sourceName, $sourceIndex = 0, $encoding = 'utf-8', Cache $cache = null, $cssOnly = false, LoggerInterface $logger = null)
     {
         $this->sourceName       = $sourceName ?: '(stdin)';
         $this->sourceIndex      = $sourceIndex;
@@ -132,6 +154,7 @@ class Parser
         $this->commentsSeen     = [];
         $this->allowVars        = true;
         $this->cssOnly          = $cssOnly;
+        $this->logger = $logger ?: new QuietLogger();
 
         if (empty(static::$operatorPattern)) {
             static::$operatorPattern = '([*\/%+-]|[!=]\=|\>\=?|\<\=?|and|or)';
@@ -168,6 +191,8 @@ class Parser
      *
      * @param string $msg
      *
+     * @phpstan-return never-return
+     *
      * @throws ParserException
      *
      * @deprecated use "parseError" and throw the exception in the caller instead.
@@ -292,7 +317,7 @@ class Parser
      * @param string       $buffer
      * @param string|array $out
      *
-     * @return boolean
+     * @return bool
      */
     public function parseValue($buffer, &$out)
     {
@@ -321,7 +346,7 @@ class Parser
      * @param string|array $out
      * @param bool         $shouldValidate
      *
-     * @return boolean
+     * @return bool
      */
     public function parseSelector($buffer, &$out, $shouldValidate = true)
     {
@@ -358,7 +383,7 @@ class Parser
      * @param string       $buffer
      * @param string|array $out
      *
-     * @return boolean
+     * @return bool
      */
     public function parseMediaQueryList($buffer, &$out)
     {
@@ -415,7 +440,7 @@ class Parser
      * position into $s. Then if a chain fails, use $this->seek($s) to
      * go back where we started.
      *
-     * @return boolean
+     * @return bool
      */
     protected function parseChunk()
     {
@@ -434,7 +459,8 @@ class Parser
             ) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false, $s);
 
-                $atRoot = $this->pushSpecialBlock(Type::T_AT_ROOT, $s);
+                $atRoot = new AtRootBlock();
+                $this->registerPushedBlock($atRoot, $s);
                 $atRoot->selector = $selector;
                 $atRoot->with     = $with;
 
@@ -448,7 +474,8 @@ class Parser
                 $this->mediaQueryList($mediaQueryList) &&
                 $this->matchChar('{', false)
             ) {
-                $media = $this->pushSpecialBlock(Type::T_MEDIA, $s);
+                $media = new MediaBlock();
+                $this->registerPushedBlock($media, $s);
                 $media->queryList = $mediaQueryList[2];
 
                 return true;
@@ -464,7 +491,8 @@ class Parser
             ) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false, $s);
 
-                $mixin = $this->pushSpecialBlock(Type::T_MIXIN, $s);
+                $mixin = new CallableBlock(Type::T_MIXIN);
+                $this->registerPushedBlock($mixin, $s);
                 $mixin->name = $mixinName;
                 $mixin->args = $args;
 
@@ -496,7 +524,8 @@ class Parser
                 ];
 
                 if (! empty($hasBlock)) {
-                    $include = $this->pushSpecialBlock(Type::T_INCLUDE, $s);
+                    $include = new ContentBlock();
+                    $this->registerPushedBlock($include, $s);
                     $include->child = $child;
                 } else {
                     $this->append($child, $s);
@@ -514,6 +543,10 @@ class Parser
             ) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false, $s);
 
+                list($line, $column) = $this->getSourcePosition($s);
+                $file = $this->sourceName;
+                $this->logger->warn("The \"@scssphp-import-once\" directive is deprecated and will be removed in ScssPhp 2.0, in \"$file\", line $line, column $column.", true);
+
                 $this->append([Type::T_SCSSPHP_IMPORT_ONCE, $importPath], $s);
 
                 return true;
@@ -582,7 +615,8 @@ class Parser
             ) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false, $s);
 
-                $func = $this->pushSpecialBlock(Type::T_FUNCTION, $s);
+                $func = new CallableBlock(Type::T_FUNCTION);
+                $this->registerPushedBlock($func, $s);
                 $func->name = $fnName;
                 $func->args = $args;
 
@@ -614,7 +648,8 @@ class Parser
             ) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false, $s);
 
-                $each = $this->pushSpecialBlock(Type::T_EACH, $s);
+                $each = new EachBlock();
+                $this->registerPushedBlock($each, $s);
 
                 foreach ($varNames[2] as $varName) {
                     $each->vars[] = $varName[1];
@@ -643,7 +678,8 @@ class Parser
                     $cond = reset($cond[2]);
                 }
 
-                $while = $this->pushSpecialBlock(Type::T_WHILE, $s);
+                $while = new WhileBlock();
+                $this->registerPushedBlock($while, $s);
                 $while->cond = $cond;
 
                 return true;
@@ -663,7 +699,8 @@ class Parser
             ) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false, $s);
 
-                $for = $this->pushSpecialBlock(Type::T_FOR, $s);
+                $for = new ForBlock();
+                $this->registerPushedBlock($for, $s);
                 $for->var   = $varName[1];
                 $for->start = $start;
                 $for->end   = $end;
@@ -680,7 +717,8 @@ class Parser
             ) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false, $s);
 
-                $if = $this->pushSpecialBlock(Type::T_IF, $s);
+                $if = new IfBlock();
+                $this->registerPushedBlock($if, $s);
 
                 while (
                     $cond[0] === Type::T_LIST &&
@@ -759,20 +797,21 @@ class Parser
 
             if (isset($last) && $last[0] === Type::T_IF) {
                 list(, $if) = $last;
+                assert($if instanceof IfBlock);
 
                 if ($this->literal('@else', 5)) {
                     if ($this->matchChar('{', false)) {
-                        $else = $this->pushSpecialBlock(Type::T_ELSE, $s);
+                        $else = new ElseBlock();
                     } elseif (
                         $this->literal('if', 2) &&
                         $this->functionCallArgumentsList($cond, false, '{', false)
                     ) {
-                        $else = $this->pushSpecialBlock(Type::T_ELSEIF, $s);
+                        $else = new ElseifBlock();
                         $else->cond = $cond;
                     }
 
                     if (isset($else)) {
-                        $else->dontAppend = true;
+                        $this->registerPushedBlock($else, $s);
                         $if->cases[] = $else;
 
                         return true;
@@ -810,7 +849,8 @@ class Parser
                 ($t1 = $this->supportsQuery($supportQuery)) &&
                 ($t2 = $this->matchChar('{', false))
             ) {
-                $directive = $this->pushSpecialBlock(Type::T_DIRECTIVE, $s);
+                $directive = new DirectiveBlock();
+                $this->registerPushedBlock($directive, $s);
                 $directive->name  = 'supports';
                 $directive->value = $supportQuery;
 
@@ -831,11 +871,12 @@ class Parser
                     $dirName = [Type::T_STRING, '', $dirName];
                 }
                 if ($dirName === 'media') {
-                    $directive = $this->pushSpecialBlock(Type::T_MEDIA, $s);
+                    $directive = new MediaBlock();
                 } else {
-                    $directive = $this->pushSpecialBlock(Type::T_DIRECTIVE, $s);
+                    $directive = new DirectiveBlock();
                     $directive->name = $dirName;
                 }
+                $this->registerPushedBlock($directive, $s);
 
                 if (isset($dirValue)) {
                     ! $this->cssOnly || ($dirValue = $this->assertPlainCssValid($dirValue));
@@ -973,11 +1014,6 @@ class Parser
 
         $this->seek($s);
 
-        // misc
-        if ($this->literal('-->', 3)) {
-            return true;
-        }
-
         // opening css block
         if (
             $this->selectors($selectors) &&
@@ -1016,7 +1052,8 @@ class Parser
             if ($this->matchChar('{', false)) {
                 ! $this->cssOnly || $this->assertPlainCssValid(false);
 
-                $propBlock = $this->pushSpecialBlock(Type::T_NESTED_PROPERTY, $s);
+                $propBlock = new NestedPropertyBlock();
+                $this->registerPushedBlock($propBlock, $s);
                 $propBlock->prefix = $name;
                 $propBlock->hasValue = $foundSomething;
 
@@ -1042,12 +1079,13 @@ class Parser
                 }
             }
 
-            if (isset($block->type) && $block->type === Type::T_INCLUDE) {
+            if ($block instanceof ContentBlock) {
                 $include = $block->child;
+                assert(\is_array($include));
                 unset($block->child);
                 $include[3] = $block;
                 $this->append($include, $s);
-            } elseif (empty($block->dontAppend)) {
+            } elseif (!$block instanceof ElseBlock && !$block instanceof ElseifBlock) {
                 $type = isset($block->type) ? $block->type : Type::T_BLOCK;
                 $this->append([$type, $block], $s);
             }
@@ -1065,10 +1103,7 @@ class Parser
         }
 
         // extra stuff
-        if (
+        if ($this->matchChar(';')) {
-            $this->matchChar(';') ||
-            $this->literal('<!--', 4)
-        ) {
             return true;
         }
 
@@ -1079,20 +1114,34 @@ class Parser
      * Push block onto parse tree
      *
      * @param array|null $selectors
-     * @param integer $pos
+     * @param int        $pos
      *
      * @return Block
      */
     protected function pushBlock($selectors, $pos = 0)
+    {
+        $b = new Block();
+        $b->selectors = $selectors;
+
+        $this->registerPushedBlock($b, $pos);
+
+        return $b;
+    }
+
+    /**
+     * @param Block $b
+     * @param int   $pos
+     *
+     * @return void
+     */
+    private function registerPushedBlock(Block $b, $pos)
     {
         list($line, $column) = $this->getSourcePosition($pos);
 
-        $b = new Block();
         $b->sourceName   = $this->sourceName;
         $b->sourceLine   = $line;
         $b->sourceColumn = $column;
         $b->sourceIndex  = $this->sourceIndex;
-        $b->selectors    = $selectors;
         $b->comments     = [];
         $b->parent       = $this->env;
 
@@ -1117,15 +1166,15 @@ class Parser
                 $this->append(null);
             }
         }
-
-        return $b;
     }
 
     /**
      * Push special (named) block onto parse tree
      *
+     * @deprecated
+     *
      * @param string  $type
-     * @param integer $pos
+     * @param int     $pos
      *
      * @return Block
      */
@@ -1174,11 +1223,11 @@ class Parser
     /**
      * Peek input stream
      *
-     * @param string  $regex
+     * @param string $regex
-     * @param array   $out
+     * @param array  $out
-     * @param integer $from
+     * @param int    $from
      *
-     * @return integer
+     * @return int
      */
     protected function peek($regex, &$out, $from = null)
     {
@@ -1187,7 +1236,7 @@ class Parser
         }
 
         $r = '/' . $regex . '/' . $this->patternModifiers;
-        $result = preg_match($r, $this->buffer, $out, null, $from);
+        $result = preg_match($r, $this->buffer, $out, 0, $from);
 
         return $result;
     }
@@ -1195,7 +1244,7 @@ class Parser
     /**
      * Seek to position in input stream (or return current position in input stream)
      *
-     * @param integer $where
+     * @param int $where
      */
     protected function seek($where)
     {
@@ -1206,7 +1255,8 @@ class Parser
      * Assert a parsed part is plain CSS Valid
      *
      * @param array|false $parsed
-     * @param int $startPos
+     * @param int         $startPos
+     *
      * @throws ParserException
      */
     protected function assertPlainCssValid($parsed, $startPos = null)
@@ -1234,7 +1284,10 @@ class Parser
 
     /**
      * Check a parsed element is plain CSS Valid
+     *
      * @param array $parsed
+     * @param bool  $allowExpression
+     *
      * @return bool|array
      */
     protected function isPlainCssValidElement($parsed, $allowExpression = false)
@@ -1255,6 +1308,7 @@ class Parser
                 'grayscale',
                 'hsl',
                 'hsla',
+                'hwb',
                 'invert',
                 'linear-gradient',
                 'min',
@@ -1413,7 +1467,7 @@ class Parser
      * @param array  $m     Matches (passed by reference)
      * @param string $delim Delimiter
      *
-     * @return boolean True if match; false otherwise
+     * @return bool True if match; false otherwise
      */
     protected function matchString(&$m, $delim)
     {
@@ -1449,17 +1503,17 @@ class Parser
     /**
      * Try to match something on head of buffer
      *
-     * @param string  $regex
+     * @param string $regex
-     * @param array   $out
+     * @param array  $out
-     * @param boolean $eatWhitespace
+     * @param bool   $eatWhitespace
      *
-     * @return boolean
+     * @return bool
      */
     protected function match($regex, &$out, $eatWhitespace = null)
     {
         $r = '/' . $regex . '/' . $this->patternModifiers;
 
-        if (! preg_match($r, $this->buffer, $out, null, $this->count)) {
+        if (! preg_match($r, $this->buffer, $out, 0, $this->count)) {
             return false;
         }
 
@@ -1479,10 +1533,10 @@ class Parser
     /**
      * Match a single string
      *
-     * @param string  $char
+     * @param string $char
-     * @param boolean $eatWhitespace
+     * @param bool   $eatWhitespace
      *
-     * @return boolean
+     * @return bool
      */
     protected function matchChar($char, $eatWhitespace = null)
     {
@@ -1506,11 +1560,11 @@ class Parser
     /**
      * Match literal string
      *
-     * @param string  $what
+     * @param string $what
-     * @param integer $len
+     * @param int    $len
-     * @param boolean $eatWhitespace
+     * @param bool   $eatWhitespace
      *
-     * @return boolean
+     * @return bool
      */
     protected function literal($what, $len, $eatWhitespace = null)
     {
@@ -1534,13 +1588,13 @@ class Parser
     /**
      * Match some whitespace
      *
-     * @return boolean
+     * @return bool
      */
     protected function whitespace()
     {
         $gotWhite = false;
 
-        while (preg_match(static::$whitePattern, $this->buffer, $m, null, $this->count)) {
+        while (preg_match(static::$whitePattern, $this->buffer, $m, 0, $this->count)) {
             if (isset($m[1]) && empty($this->commentsSeen[$this->count])) {
                 // comment that are kept in the output CSS
                 $comment = [];
@@ -1568,6 +1622,11 @@ class Parser
 
                         $comment[] = [Type::T_COMMENT, substr($this->buffer, $p, $this->count - $p), $out];
                     } else {
+                        list($line, $column) = $this->getSourcePosition($this->count);
+                        $file = $this->sourceName;
+                        if (!$this->discardComments) {
+                            $this->logger->warn("Unterminated interpolations in multiline comments are deprecated and will be removed in ScssPhp 2.0, in \"$file\", line $line, column $column.", true);
+                        }
                         $comment[] = substr($this->buffer, $this->count, 2);
 
                         $this->count += 2;
@@ -1585,7 +1644,14 @@ class Parser
                 } else {
                     $comment[] = $c;
                     $staticComment = substr($this->buffer, $startCommentCount, $endCommentCount - $startCommentCount);
-                    $this->appendComment([Type::T_COMMENT, $staticComment, [Type::T_STRING, '', $comment]]);
+                    $commentStatement = [Type::T_COMMENT, $staticComment, [Type::T_STRING, '', $comment]];
+
+                    list($line, $column) = $this->getSourcePosition($startCommentCount);
+                    $commentStatement[self::SOURCE_LINE] = $line;
+                    $commentStatement[self::SOURCE_COLUMN] = $column;
+                    $commentStatement[self::SOURCE_INDEX] = $this->sourceIndex;
+
+                    $this->appendComment($commentStatement);
                 }
 
                 $this->commentsSeen[$startCommentCount] = true;
@@ -1621,7 +1687,7 @@ class Parser
      * Append statement to current block
      *
      * @param array|null $statement
-     * @param integer $pos
+     * @param int        $pos
      */
     protected function append($statement, $pos = null)
     {
@@ -1666,7 +1732,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function mediaQueryList(&$out)
     {
@@ -1678,7 +1744,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function mediaQuery(&$out)
     {
@@ -1732,7 +1798,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function supportsQuery(&$out)
     {
@@ -1865,7 +1931,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function mediaExpression(&$out)
     {
@@ -1898,7 +1964,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function argValues(&$out)
     {
@@ -1923,7 +1989,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function argValue(&$out)
     {
@@ -2003,10 +2069,10 @@ class Parser
     /**
      * Parse directive value list that considers $vars as keyword
      *
-     * @param array          $out
+     * @param array       $out
-     * @param boolean|string $endChar
+     * @param bool|string $endChar
      *
-     * @return boolean
+     * @return bool
      */
     protected function directiveValue(&$out, $endChar = false)
     {
@@ -2067,7 +2133,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function valueList(&$out)
     {
@@ -2083,10 +2149,11 @@ class Parser
      * Parse a function call, where externals () are part of the call
      * and not of the value list
      *
-     * @param $out
+     * @param array       $out
-     * @param bool $mandatoryEnclos
+     * @param bool        $mandatoryEnclos
      * @param null|string $charAfter
-     * @param null|bool $eatWhiteSp
+     * @param null|bool   $eatWhiteSp
+     *
      * @return bool
      */
     protected function functionCallArgumentsList(&$out, $mandatoryEnclos = true, $charAfter = null, $eatWhiteSp = null)
@@ -2123,7 +2190,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function spaceList(&$out)
     {
@@ -2133,12 +2200,12 @@ class Parser
     /**
      * Parse generic list
      *
-     * @param array   $out
+     * @param array  $out
-     * @param string  $parseItem The name of the method used to parse items
+     * @param string $parseItem The name of the method used to parse items
-     * @param string  $delim
+     * @param string $delim
-     * @param boolean $flatten
+     * @param bool   $flatten
      *
-     * @return boolean
+     * @return bool
      */
     protected function genericList(&$out, $parseItem, $delim = '', $flatten = true)
     {
@@ -2234,11 +2301,11 @@ class Parser
     /**
      * Parse expression
      *
-     * @param array   $out
+     * @param array $out
-     * @param boolean $listOnly
+     * @param bool  $listOnly
-     * @param boolean $lookForExp
+     * @param bool  $lookForExp
      *
-     * @return boolean
+     * @return bool
      */
     protected function expression(&$out, $listOnly = false, $lookForExp = true)
     {
@@ -2300,11 +2367,11 @@ class Parser
      * Parse expression specifically checking for lists in parenthesis or brackets
      *
      * @param array   $out
-     * @param integer $s
+     * @param int     $s
      * @param string  $closingParen
      * @param array   $allowedTypes
      *
-     * @return boolean
+     * @return bool
      */
     protected function enclosedExpression(&$out, $s, $closingParen = ')', $allowedTypes = [Type::T_LIST, Type::T_MAP])
     {
@@ -2359,8 +2426,8 @@ class Parser
     /**
      * Parse left-hand side of subexpression
      *
-     * @param array   $lhs
+     * @param array $lhs
-     * @param integer $minP
+     * @param int   $minP
      *
      * @return array
      */
@@ -2395,10 +2462,8 @@ class Parser
                 break;
             }
 
-            // peek and see if rhs belongs to next operator
+            // consume higher-precedence operators on the right-hand side
-            if ($this->peek($operators, $next) && static::$precedence[$next[1]] > static::$precedence[$op]) {
+            $rhs = $this->expHelper($rhs, static::$precedence[$op] + 1);
-                $rhs = $this->expHelper($rhs, static::$precedence[$next[1]]);
-            }
 
             $lhs = [Type::T_EXPRESSION, $op, $lhs, $rhs, $this->inParens, $whiteBefore, $whiteAfter];
 
@@ -2417,7 +2482,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function value(&$out)
     {
@@ -2625,7 +2690,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function parenValue(&$out)
     {
@@ -2664,7 +2729,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function progid(&$out)
     {
@@ -2697,7 +2762,7 @@ class Parser
      * @param string $name
      * @param array  $func
      *
-     * @return boolean
+     * @return bool
      */
     protected function func($name, &$func)
     {
@@ -2751,7 +2816,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function argumentList(&$out)
     {
@@ -2796,7 +2861,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function argumentDef(&$out)
     {
@@ -2858,7 +2923,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function map(&$out)
     {
@@ -2900,7 +2965,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function color(&$out)
     {
@@ -2926,7 +2991,7 @@ class Parser
      *
      * @param array $unit
      *
-     * @return boolean
+     * @return bool
      */
     protected function unit(&$unit)
     {
@@ -2951,8 +3016,9 @@ class Parser
      * Parse string
      *
      * @param array $out
+     * @param bool  $keepDelimWithInterpolation
      *
-     * @return boolean
+     * @return bool
      */
     protected function string(&$out, $keepDelimWithInterpolation = false)
     {
@@ -3033,7 +3099,8 @@ class Parser
 
     /**
      * @param string $out
-     * @param bool $inKeywords
+     * @param bool   $inKeywords
+     *
      * @return bool
      */
     protected function matchEscapeCharacter(&$out, $inKeywords = false)
@@ -3083,10 +3150,10 @@ class Parser
     /**
      * Parse keyword or interpolation
      *
-     * @param array   $out
+     * @param array $out
-     * @param boolean $restricted
+     * @param bool  $restricted
      *
-     * @return boolean
+     * @return bool
      */
     protected function mixedKeyword(&$out, $restricted = false)
     {
@@ -3127,14 +3194,14 @@ class Parser
     /**
      * Parse an unbounded string stopped by $end
      *
-     * @param string  $end
+     * @param string $end
-     * @param array   $out
+     * @param array  $out
-     * @param string  $nestOpen
+     * @param string $nestOpen
-     * @param string  $nestClose
+     * @param string $nestClose
-     * @param boolean $rtrim
+     * @param bool   $rtrim
      * @param string $disallow
      *
-     * @return boolean
+     * @return bool
      */
     protected function openString($end, &$out, $nestOpen = null, $nestClose = null, $rtrim = true, $disallow = null)
     {
@@ -3210,9 +3277,9 @@ class Parser
      * Parser interpolation
      *
      * @param string|array $out
-     * @param boolean      $lookWhite save information about whitespace before and after
+     * @param bool         $lookWhite save information about whitespace before and after
      *
-     * @return boolean
+     * @return bool
      */
     protected function interpolation(&$out, $lookWhite = true)
     {
@@ -3267,7 +3334,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function propertyName(&$out)
     {
@@ -3303,7 +3370,7 @@ class Parser
         }
 
         // match comment hack
-        if (preg_match(static::$whitePattern, $this->buffer, $m, null, $this->count)) {
+        if (preg_match(static::$whitePattern, $this->buffer, $m, 0, $this->count)) {
             if (! empty($m[0])) {
                 $parts[] = $m[0];
                 $this->count += \strlen($m[0]);
@@ -3322,7 +3389,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function customProperty(&$out)
     {
@@ -3380,9 +3447,9 @@ class Parser
      * Parse comma separated selector list
      *
      * @param array $out
-     * @param string|boolean $subSelector
+     * @param string|bool $subSelector
      *
-     * @return boolean
+     * @return bool
      */
     protected function selectors(&$out, $subSelector = false)
     {
@@ -3416,9 +3483,9 @@ class Parser
      * Parse whitespace separated selector list
      *
      * @param array          $out
-     * @param string|boolean $subSelector
+     * @param string|bool $subSelector
      *
-     * @return boolean
+     * @return bool
      */
     protected function selector(&$out, $subSelector = false)
     {
@@ -3474,7 +3541,8 @@ class Parser
      * - but this require a better formal selector representation instead of the array we have now
      *
      * @param string $out
-     * @param bool $keepEscapedNumber
+     * @param bool   $keepEscapedNumber
+     *
      * @return bool
      */
     protected function matchEscapeCharacterInSelector(&$out, $keepEscapedNumber = false)
@@ -3519,9 +3587,9 @@ class Parser
      * }}
      *
      * @param array          $out
-     * @param string|boolean $subSelector
+     * @param string|bool $subSelector
      *
-     * @return boolean
+     * @return bool
      */
     protected function selectorSingle(&$out, $subSelector = false)
     {
@@ -3745,7 +3813,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function variable(&$out)
     {
@@ -3772,11 +3840,11 @@ class Parser
     /**
      * Parse a keyword
      *
-     * @param string  $word
+     * @param string $word
-     * @param boolean $eatWhitespace
+     * @param bool   $eatWhitespace
-     * @param boolean $inSelector
+     * @param bool   $inSelector
      *
-     * @return boolean
+     * @return bool
      */
     protected function keyword(&$word, $eatWhitespace = null, $inSelector = false)
     {
@@ -3839,11 +3907,11 @@ class Parser
     /**
      * Parse a keyword that should not start with a number
      *
-     * @param string  $word
+     * @param string $word
-     * @param boolean $eatWhitespace
+     * @param bool   $eatWhitespace
-     * @param boolean $inSelector
+     * @param bool   $inSelector
      *
-     * @return boolean
+     * @return bool
      */
     protected function restrictedKeyword(&$word, $eatWhitespace = null, $inSelector = false)
     {
@@ -3863,7 +3931,7 @@ class Parser
      *
      * @param string|array $placeholder
      *
-     * @return boolean
+     * @return bool
      */
     protected function placeholder(&$placeholder)
     {
@@ -3892,7 +3960,7 @@ class Parser
      *
      * @param array $out
      *
-     * @return boolean
+     * @return bool
      */
     protected function url(&$out)
     {
@@ -3927,7 +3995,7 @@ class Parser
      * Consume an end of statement delimiter
      * @param bool $eatWhitespace
      *
-     * @return boolean
+     * @return bool
      */
     protected function end($eatWhitespace = null)
     {
@@ -4045,7 +4113,7 @@ class Parser
     /**
      * Get source line number and column (given character position in the buffer)
      *
-     * @param integer $pos
+     * @param int $pos
      *
      * @return array
      */
@@ -4074,11 +4142,20 @@ class Parser
     }
 
     /**
-     * Save internal encoding
+     * Save internal encoding of mbstring
+     *
+     * When mbstring.func_overload is used to replace the standard PHP string functions,
+     * this method configures the internal encoding to a single-byte one so that the
+     * behavior matches the normal behavior of PHP string functions while using the parser.
+     * The existing internal encoding is saved and will be restored when calling {@see restoreEncoding}.
+     *
+     * If mbstring.func_overload is not used (or does not override string functions), this method is a no-op.
+     *
+     * @return void
      */
     private function saveEncoding()
     {
-        if (\extension_loaded('mbstring')) {
+        if (\PHP_VERSION_ID < 80000 && \extension_loaded('mbstring') && (2 & (int) ini_get('mbstring.func_overload')) > 0) {
             $this->encoding = mb_internal_encoding();
 
             mb_internal_encoding('iso-8859-1');
@@ -4087,6 +4164,8 @@ class Parser
 
     /**
      * Restore internal encoding
+     *
+     * @return void
      */
     private function restoreEncoding()
     {

lib/scssphp/SourceMap/Base64.php

@@ -16,11 +16,13 @@ namespace ScssPhp\ScssPhp\SourceMap;
  * Base 64 Encode/Decode
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class Base64
 {
     /**
-     * @var array
+     * @var array<int, string>
      */
     private static $encodingMap = [
         0 => 'A',
@@ -90,7 +92,7 @@ class Base64
     ];
 
     /**
-     * @var array
+     * @var array<string|int, int>
      */
     private static $decodingMap = [
         'A' => 0,
@@ -162,7 +164,7 @@ class Base64
     /**
      * Convert to base64
      *
-     * @param integer $value
+     * @param int $value
      *
      * @return string
      */
@@ -176,7 +178,7 @@ class Base64
      *
      * @param string $value
      *
-     * @return integer
+     * @return int
      */
     public static function decode($value)
     {

lib/scssphp/SourceMap/Base64VLQ.php

@@ -34,6 +34,8 @@ namespace ScssPhp\ScssPhp\SourceMap;
  *
  * @author John Lenz <johnlenz@google.com>
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class Base64VLQ
 {
@@ -49,7 +51,7 @@ class Base64VLQ
     /**
      * Returns the VLQ encoded value.
      *
-     * @param integer $value
+     * @param int $value
      *
      * @return string
      */
@@ -78,9 +80,9 @@ class Base64VLQ
      * Decodes VLQValue.
      *
      * @param string $str
-     * @param integer $index
+     * @param int    $index
      *
-     * @return integer
+     * @return int
      */
     public static function decode($str, &$index)
     {
@@ -105,9 +107,9 @@ class Base64VLQ
      *   1 becomes 2 (10 binary), -1 becomes 3 (11 binary)
      *   2 becomes 4 (100 binary), -2 becomes 5 (101 binary)
      *
-     * @param integer $value
+     * @param int $value
      *
-     * @return integer
+     * @return int
      */
     private static function toVLQSigned($value)
     {
@@ -124,9 +126,9 @@ class Base64VLQ
      *   2 (10 binary) becomes 1, 3 (11 binary) becomes -1
      *   4 (100 binary) becomes 2, 5 (101 binary) becomes -2
      *
-     * @param integer $value
+     * @param int $value
      *
-     * @return integer
+     * @return int
      */
     private static function fromVLQSigned($value)
     {

lib/scssphp/SourceMap/SourceMapGenerator.php

@@ -21,6 +21,8 @@ use ScssPhp\ScssPhp\Exception\CompilerException;
  *
  * @author Josh Schmidt <oyejorge@gmail.com>
  * @author Nicolas FRANÇOIS <nicolas.francois@frog-labs.com>
+ *
+ * @internal
  */
 class SourceMapGenerator
 {
@@ -33,6 +35,7 @@ class SourceMapGenerator
      * Array of default options
      *
      * @var array
+     * @phpstan-var array{sourceRoot: string, sourceMapFilename: string|null, sourceMapURL: string|null, sourceMapWriteTo: string|null, outputSourceFiles: bool, sourceMapRootpath: string, sourceMapBasepath: string}
      */
     protected $defaultOptions = [
         // an optional source root, useful for relocating source files
@@ -70,6 +73,7 @@ class SourceMapGenerator
      * Array of mappings
      *
      * @var array
+     * @phpstan-var list<array{generated_line: int, generated_column: int, original_line: int, original_column: int, source_file: string}>
      */
     protected $mappings = [];
 
@@ -83,16 +87,24 @@ class SourceMapGenerator
     /**
      * File to content map
      *
-     * @var array
+     * @var array<string, string>
      */
     protected $sources = [];
+
+    /**
+     * @var array<string, int>
+     */
     protected $sourceKeys = [];
 
     /**
      * @var array
+     * @phpstan-var array{sourceRoot: string, sourceMapFilename: string|null, sourceMapURL: string|null, sourceMapWriteTo: string|null, outputSourceFiles: bool, sourceMapRootpath: string, sourceMapBasepath: string}
      */
     private $options;
 
+    /**
+     * @phpstan-param array{sourceRoot?: string, sourceMapFilename?: string|null, sourceMapURL?: string|null, sourceMapWriteTo?: string|null, outputSourceFiles?: bool, sourceMapRootpath?: string, sourceMapBasepath?: string} $options
+     */
     public function __construct(array $options = [])
     {
         $this->options = array_merge($this->defaultOptions, $options);
@@ -102,11 +114,13 @@ class SourceMapGenerator
     /**
      * Adds a mapping
      *
-     * @param integer $generatedLine   The line number in generated file
+     * @param int    $generatedLine   The line number in generated file
-     * @param integer $generatedColumn The column number in generated file
+     * @param int    $generatedColumn The column number in generated file
-     * @param integer $originalLine    The line number in original file
+     * @param int    $originalLine    The line number in original file
-     * @param integer $originalColumn  The column number in original file
+     * @param int    $originalColumn  The column number in original file
-     * @param string  $sourceFile      The original source file
+     * @param string $sourceFile      The original source file
+     *
+     * @return void
      */
     public function addMapping($generatedLine, $generatedColumn, $originalLine, $originalColumn, $sourceFile)
     {
@@ -129,6 +143,7 @@ class SourceMapGenerator
      * @return string
      *
      * @throws \ScssPhp\ScssPhp\Exception\CompilerException If the file could not be saved
+     * @deprecated
      */
     public function saveMap($content)
     {
@@ -214,7 +229,7 @@ class SourceMapGenerator
     /**
      * Returns the sources contents
      *
-     * @return array|null
+     * @return string[]|null
      */
     protected function getSourcesContent()
     {
@@ -311,7 +326,7 @@ class SourceMapGenerator
      *
      * @param string $filename
      *
-     * @return integer|false
+     * @return int|false
      */
     protected function findFileIndex($filename)
     {
@@ -347,8 +362,8 @@ class SourceMapGenerator
     /**
      * Fix windows paths
      *
-     * @param string  $path
+     * @param string $path
-     * @param boolean $addEndSlash
+     * @param bool   $addEndSlash
      *
      * @return string
      */

lib/scssphp/Type.php

@@ -19,57 +19,190 @@ namespace ScssPhp\ScssPhp;
  */
 class Type
 {
+    /**
+     * @internal
+     */
     const T_ASSIGN = 'assign';
+    /**
+     * @internal
+     */
     const T_AT_ROOT = 'at-root';
+    /**
+     * @internal
+     */
     const T_BLOCK = 'block';
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @internal
+     */
     const T_BREAK = 'break';
+    /**
+     * @internal
+     */
     const T_CHARSET = 'charset';
     const T_COLOR = 'color';
+    /**
+     * @internal
+     */
     const T_COMMENT = 'comment';
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @internal
+     */
     const T_CONTINUE = 'continue';
-    /** @deprecated */
+    /**
+     * @deprecated
+     * @internal
+     */
     const T_CONTROL = 'control';
+    /**
+     * @internal
+     */
     const T_CUSTOM_PROPERTY = 'custom';
+    /**
+     * @internal
+     */
     const T_DEBUG = 'debug';
+    /**
+     * @internal
+     */
     const T_DIRECTIVE = 'directive';
+    /**
+     * @internal
+     */
     const T_EACH = 'each';
+    /**
+     * @internal
+     */
     const T_ELSE = 'else';
+    /**
+     * @internal
+     */
     const T_ELSEIF = 'elseif';
+    /**
+     * @internal
+     */
     const T_ERROR = 'error';
+    /**
+     * @internal
+     */
     const T_EXPRESSION = 'exp';
+    /**
+     * @internal
+     */
     const T_EXTEND = 'extend';
+    /**
+     * @internal
+     */
     const T_FOR = 'for';
     const T_FUNCTION = 'function';
+    /**
+     * @internal
+     */
     const T_FUNCTION_REFERENCE = 'function-reference';
+    /**
+     * @internal
+     */
     const T_FUNCTION_CALL = 'fncall';
+    /**
+     * @internal
+     */
     const T_HSL = 'hsl';
+    /**
+     * @internal
+     */
+    const T_HWB = 'hwb';
+    /**
+     * @internal
+     */
     const T_IF = 'if';
+    /**
+     * @internal
+     */
     const T_IMPORT = 'import';
+    /**
+     * @internal
+     */
     const T_INCLUDE = 'include';
+    /**
+     * @internal
+     */
     const T_INTERPOLATE = 'interpolate';
+    /**
+     * @internal
+     */
     const T_INTERPOLATED = 'interpolated';
+    /**
+     * @internal
+     */
     const T_KEYWORD = 'keyword';
     const T_LIST = 'list';
     const T_MAP = 'map';
+    /**
+     * @internal
+     */
     const T_MEDIA = 'media';
+    /**
+     * @internal
+     */
     const T_MEDIA_EXPRESSION = 'mediaExp';
+    /**
+     * @internal
+     */
     const T_MEDIA_TYPE = 'mediaType';
+    /**
+     * @internal
+     */
     const T_MEDIA_VALUE = 'mediaValue';
+    /**
+     * @internal
+     */
     const T_MIXIN = 'mixin';
+    /**
+     * @internal
+     */
     const T_MIXIN_CONTENT = 'mixin_content';
+    /**
+     * @internal
+     */
     const T_NESTED_PROPERTY = 'nestedprop';
+    /**
+     * @internal
+     */
     const T_NOT = 'not';
     const T_NULL = 'null';
     const T_NUMBER = 'number';
+    /**
+     * @internal
+     */
     const T_RETURN = 'return';
+    /**
+     * @internal
+     */
     const T_ROOT = 'root';
+    /**
+     * @internal
+     */
     const T_SCSSPHP_IMPORT_ONCE = 'scssphp-import-once';
+    /**
+     * @internal
+     */
     const T_SELF = 'self';
     const T_STRING = 'string';
+    /**
+     * @internal
+     */
     const T_UNARY = 'unary';
+    /**
+     * @internal
+     */
     const T_VARIABLE = 'var';
+    /**
+     * @internal
+     */
     const T_WARN = 'warn';
+    /**
+     * @internal
+     */
     const T_WHILE = 'while';
 }

lib/scssphp/Util.php

@@ -14,11 +14,14 @@ namespace ScssPhp\ScssPhp;
 
 use ScssPhp\ScssPhp\Base\Range;
 use ScssPhp\ScssPhp\Exception\RangeException;
+use ScssPhp\ScssPhp\Node\Number;
 
 /**
- * Utilty functions
+ * Utility functions
  *
  * @author Anthon Pang <anthon.pang@gmail.com>
+ *
+ * @internal
  */
 class Util
 {
@@ -26,10 +29,10 @@ class Util
      * Asserts that `value` falls within `range` (inclusive), leaving
      * room for slight floating-point errors.
      *
-     * @param string                    $name  The name of the value. Used in the error message.
+     * @param string       $name  The name of the value. Used in the error message.
-     * @param \ScssPhp\ScssPhp\Base\Range $range Range of values.
+     * @param Range        $range Range of values.
-     * @param array                     $value The value to check.
+     * @param array|Number $value The value to check.
-     * @param string                    $unit  The unit of the value. Used in error reporting.
+     * @param string       $unit  The unit of the value. Used in error reporting.
      *
      * @return mixed `value` adjusted to fall within range, if it was outside by a floating-point margin.
      *
@@ -76,7 +79,7 @@ class Util
     /**
      * mb_chr() wrapper
      *
-     * @param integer $code
+     * @param int $code
      *
      * @return string
      */
@@ -115,10 +118,10 @@ class Util
         }
 
         if (\function_exists('iconv_strlen')) {
-            return @iconv_strlen($string, 'UTF-8');
+            return (int) @iconv_strlen($string, 'UTF-8');
         }
 
-        return strlen($string);
+        throw new \LogicException('Either mbstring (recommended) or iconv is necessary to use Scssphp.');
     }
 
     /**
@@ -155,7 +158,7 @@ class Util
             return (string)iconv_substr($string, $start, $length, 'UTF-8');
         }
 
-        return substr($string, $start, $length);
+        throw new \LogicException('Either mbstring (recommended) or iconv is necessary to use Scssphp.');
     }
 
     /**
@@ -176,6 +179,6 @@ class Util
             return iconv_strpos($haystack, $needle, $offset, 'UTF-8');
         }
 
-        return strpos($haystack, $needle, $offset);
+        throw new \LogicException('Either mbstring (recommended) or iconv is necessary to use Scssphp.');
     }
 }

lib/scssphp/ValueConverter.php

@@ -0,0 +1,95 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp;
+
+use ScssPhp\ScssPhp\Node\Number;
+
+final class ValueConverter
+{
+    // Prevent instantiating it
+    private function __construct()
+    {
+    }
+
+    /**
+     * Parses a value from a Scss source string.
+     *
+     * The returned value is guaranteed to be supported by the
+     * Compiler methods for registering custom variables. No other
+     * guarantee about it is provided. It should be considered
+     * opaque values by the caller.
+     *
+     * @param string $source
+     *
+     * @return mixed
+     */
+    public static function parseValue($source)
+    {
+        $parser = new Parser(__CLASS__);
+
+        if (!$parser->parseValue($source, $value)) {
+            throw new \InvalidArgumentException(sprintf('Invalid value source "%s".', $source));
+        }
+
+        return $value;
+    }
+
+    /**
+     * Converts a PHP value to a Sass value
+     *
+     * The returned value is guaranteed to be supported by the
+     * Compiler methods for registering custom variables. No other
+     * guarantee about it is provided. It should be considered
+     * opaque values by the caller.
+     *
+     * @param mixed $value
+     *
+     * @return mixed
+     */
+    public static function fromPhp($value)
+    {
+        if ($value instanceof Number) {
+            return $value;
+        }
+
+        if (is_array($value) && isset($value[0]) && \in_array($value[0], [Type::T_NULL, Type::T_COLOR, Type::T_KEYWORD, Type::T_LIST, Type::T_MAP, Type::T_STRING])) {
+            return $value;
+        }
+
+        if ($value === null) {
+            return Compiler::$null;
+        }
+
+        if ($value === true) {
+            return Compiler::$true;
+        }
+
+        if ($value === false) {
+            return Compiler::$false;
+        }
+
+        if ($value === '') {
+            return Compiler::$emptyString;
+        }
+
+        if (\is_int($value) || \is_float($value)) {
+            return new Number($value, '');
+        }
+
+        if (\is_string($value)) {
+            return [Type::T_STRING, '"', [$value]];
+        }
+
+        throw new \InvalidArgumentException(sprintf('Cannot convert the value of type "%s" to a Sass value.', gettype($value)));
+    }
+}

lib/scssphp/Version.php

@@ -19,5 +19,5 @@ namespace ScssPhp\ScssPhp;
  */
 class Version
 {
-    const VERSION = '1.4.1';
+    const VERSION = '1.10.0';
 }

lib/scssphp/Warn.php

@@ -0,0 +1,84 @@
+<?php
+
+/**
+ * SCSSPHP
+ *
+ * @copyright 2012-2020 Leaf Corcoran
+ *
+ * @license http://opensource.org/licenses/MIT MIT
+ *
+ * @link http://scssphp.github.io/scssphp
+ */
+
+namespace ScssPhp\ScssPhp;
+
+final class Warn
+{
+    /**
+     * @var callable|null
+     * @phpstan-var (callable(string, bool): void)|null
+     */
+    private static $callback;
+
+    /**
+     * Prints a warning message associated with the current `@import` or function call.
+     *
+     * This may only be called within a custom function or importer callback.
+     *
+     * @param string $message
+     *
+     * @return void
+     */
+    public static function warning($message)
+    {
+        self::reportWarning($message, false);
+    }
+
+    /**
+     * Prints a deprecation warning message associated with the current `@import` or function call.
+     *
+     * This may only be called within a custom function or importer callback.
+     *
+     * @param string $message
+     *
+     * @return void
+     */
+    public static function deprecation($message)
+    {
+        self::reportWarning($message, true);
+    }
+
+    /**
+     * @param callable|null $callback
+     *
+     * @return callable|null The previous warn callback
+     *
+     * @phpstan-param (callable(string, bool): void)|null $callback
+     *
+     * @phpstan-return (callable(string, bool): void)|null
+     *
+     * @internal
+     */
+    public static function setCallback(callable $callback = null)
+    {
+        $previousCallback = self::$callback;
+        self::$callback = $callback;
+
+        return $previousCallback;
+    }
+
+    /**
+     * @param string $message
+     * @param bool   $deprecation
+     *
+     * @return void
+     */
+    private static function reportWarning($message, $deprecation)
+    {
+        if (self::$callback === null) {
+            throw new \BadMethodCallException('The warning Reporter may only be called within a custom function or importer callback.');
+        }
+
+        \call_user_func(self::$callback, $message, $deprecation);
+    }
+}