Update Scss task

docs/tasks/Assets.md

@@ -2,7 +2,6 @@
 
 ## ImageMinify
 
-
 Minifies images.
 
 When the task is run without any specified minifier it will compress the
@@ -23,12 +22,12 @@ This will use the following minifiers based in the extension:
 
 When the required minifier is not installed on the system the task will try
 to download it from the [imagemin](https://github.com/imagemin) repository
-into a local directory.
-This directory is `vendor/bin/` by default and may be changed:
+into a local directory. This directory is `vendor/bin/` by default and may be
+changed:
 
 ```php
 $this->taskImageMinify('assets/images/*')
-    ->setExecutableDir('/tmp/imagemin/bin/)
+    ->setExecutableDir('/tmp/imagemin/bin/')
     ->to('dist/images/')
     ->run();
 ```
@@ -39,7 +38,7 @@ files. In that case it is useful to filter the files with the extension:
 ```php
 $this->taskImageMinify('assets/images/*.png')
     ->to('dist/images/')
-    ->minifier('pngcrush');
+    ->minifier('pngcrush')
     ->run();
 ```
 
@@ -70,21 +69,16 @@ This will execute as:
 `jpegtran -copy none -progressive -optimize -outfile "dist/images/test.jpg" "/var/www/test/assets/images/test.jpg"`
 
 * `setExecutableDir($directory)`
-
- * `param string` $directory
+  * `param string` $directory
 * `to($target)`
-
- * `param string` $target
+  * `param string` $target
 * `minifier($minifier, array $options = array ( ))`
-
- * `param string` $minifier
+  * `param string` $minifier
 * `setOutput($output)`
-
- * `param \Symfony\Component\Console\Output\OutputInterface` $output
+  * `param \Symfony\Component\Console\Output\OutputInterface` $output
 
 ## Less
 
-
 Compiles less files.
 
 ```php
@@ -121,35 +115,29 @@ method named after them and overloading the lessCompilers() method to
 inject the name there.
 
 * `importDir($dirs)`
-
- * `see` CssPreprocessor::setImportPaths
+  * `see` CssPreprocessor::setImportPaths
 * `addImportPath($dir)`
-
- * `param string` $dir
+  * `param string` $dir
 * `setImportPaths($dirs)`
-
- * `param array|string` $dirs
+  * `param array|string` $dirs
 * `setFormatter($formatterName)`
-
- * `param string` $formatterName
+  * `param string` $formatterName
 * `compiler($compiler, array $options = array ( ))`
-
- * `param string` $compiler
+  * `param string` $compiler
 * `setOutput($output)`
-
- * `param \Symfony\Component\Console\Output\OutputInterface` $output
+  * `param \Symfony\Component\Console\Output\OutputInterface` $output
 
 ## Minify
 
-
 Minifies an asset file (CSS or JS).
 
-``` php
+```php
 <?php
 $this->taskMinify('web/assets/theme.css')
-     ->run()
+    ->run();
 ?>
 ```
+
 Please install additional packages to use this task:
 
 ```
@@ -158,30 +146,22 @@ composer require natxet/cssmin:^3.0
 ```
 
 * `to($dst)`
-
- * `param string` $dst
+  * `param string` $dst
 * `type($type)`
-
- * `param string` $type Allowed values: "css", "js".
+  * `param string` $type Allowed values: "css", "js".
 * `singleLine($singleLine)`
-
- * `param bool` $singleLine
+  * `param bool` $singleLine
 * `keepImportantComments($keepImportantComments)`
-
- * `param bool` $keepImportantComments
+  * `param bool` $keepImportantComments
 * `specialVarRx($specialVarRx)`
-
- * `param bool` $specialVarRx
+  * `param bool` $specialVarRx
 * `__toString()`
-
- * `return string`
+  * `return string`
 * `setOutput($output)`
-
- * `param \Symfony\Component\Console\Output\OutputInterface` $output
+  * `param \Symfony\Component\Console\Output\OutputInterface` $output
 
 ## Scss
 
-
 Compiles scss files.
 
 ```php
@@ -194,33 +174,40 @@ $this->taskScss([
 ?>
 ```
 
-Use the following scss compiler in your project:
+Use one of both scss compilers in your project:
 
 ```
-"scssphp/scssphp ": "~1.0.0",
+"scssphp/scssphp": "^2.1",
+"bugo/scss-php": "^0.7"
+```
+
+Specify directory (string or array) for scss imports lookup:
+
+```php
+<?php
+$this->taskScss([
+    'scss/default.scss' => 'css/default.css'
+])
+->importDir('scss')
+->compiler('scss')
+->run();
+?>
 ```
 
 You can implement additional compilers by extending this task and adding a
 method named after them and overloading the scssCompilers() method to
 inject the name there.
 
 * `setFormatter($formatterName)`
-
- * `link` https://scssphp.github.io/scssphp/docs/#output-formatting
+  * `link` https://scssphp.github.io/scssphp/docs/#output-formatting
+  * Accepts `expanded` and `compressed`; legacy formatter class names from scssphp 1.x are also supported.
 * `importDir($dirs)`
-
- * `see` CssPreprocessor::setImportPaths
+  * `see` CssPreprocessor::setImportPaths
 * `addImportPath($dir)`
-
- * `param string` $dir
+  * `param string` $dir
 * `setImportPaths($dirs)`
-
- * `param array|string` $dirs
+  * `param array|string` $dirs
 * `compiler($compiler, array $options = array ( ))`
-
- * `param string` $compiler
+  * `param string` $compiler
 * `setOutput($output)`
-
- * `param \Symfony\Component\Console\Output\OutputInterface` $output
-
-
+  * `param \Symfony\Component\Console\Output\OutputInterface` $output

src/Task/Assets/Scss.php

@@ -17,10 +17,24 @@
  * ?>
  * ```
  *
- * Use the following scss compiler in your project:
+ * Use one of both scss compilers in your project:
  *
  * ```
- * "scssphp/scssphp ": "~1.0.0",
+ * "scssphp/scssphp": "^2.1",
+ * "bugo/scss-php": "^0.7"
+ * ```
+ *
+ * Specify directory (string or array) for scss imports lookup:
+ *
+ * ```php
+ * <?php
+ * $this->taskScss([
+ *     'scss/default.scss' => 'css/default.css'
+ * ])
+ * ->importDir('scss')
+ * ->compiler('scss')
+ * ->run();
+ * ?>
  * ```
  *
  * You can implement additional compilers by extending this task and adding a
@@ -36,6 +50,7 @@ class Scss extends CssPreprocessor
      */
     protected $compilers = [
         'scssphp', // https://github.com/scssphp/scssphp
+        'scss', // https://github.com/dragomano/scss-php
     ];
 
     /**
@@ -52,34 +67,105 @@ protected function scssphp($file)
             return Result::errorMissingPackage($this, 'scssphp', 'scssphp/scssphp');
         }
 
-        $scssCode = file_get_contents($file);
         $scss = new \ScssPhp\ScssPhp\Compiler();
 
-        // set options for the scssphp compiler
         if (isset($this->compilerOptions['importDirs'])) {
             $scss->setImportPaths($this->compilerOptions['importDirs']);
         }
 
         if (isset($this->compilerOptions['formatter'])) {
-            $scss->setFormatter($this->compilerOptions['formatter']);
+            $scss->setOutputStyle($this->normalizeScssPhpOutputStyle($this->compilerOptions['formatter']));
         }
 
-        return $scss->compile($scssCode);
+        return $scss->compileFile($file)->getCss();
     }
 
     /**
-     * Sets the formatter for scssphp
+     * bugo/scss-php compiler
+     * @link https://github.com/dragomano/scss-php
+     *
+     * @param string $file
      *
-     * The method setFormatter($formatterName) sets the current formatter to $formatterName,
-     * the name of a class as a string that implements the formatting interface. See the source
-     * for ScssPhp\ScssPhp\Formatter\Expanded for an example.
+     * @return string|\Robo\Result
+     */
+    protected function scss($file)
+    {
+        if (!class_exists('\Bugo\SCSS\Compiler')) {
+            return Result::errorMissingPackage($this, 'Bugo\\SCSS\\Compiler', 'bugo/scss-php');
+        }
+
+        $loader = isset($this->compilerOptions['importDirs'])
+            ? new \Bugo\SCSS\Loader($this->compilerOptions['importDirs'])
+            : new \Bugo\SCSS\Loader();
+
+        $compiler = new \Bugo\SCSS\Compiler(
+            new \Bugo\SCSS\CompilerOptions(
+                style: $this->normalizeBugoOutputStyle($this->compilerOptions['formatter'] ?? null)
+            ),
+            $loader
+        );
+
+        return $compiler->compileFile($file);
+    }
+
+    /**
+     * @param string|null $formatter
+     *
+     * @return \ScssPhp\ScssPhp\OutputStyle
+     */
+    protected function normalizeScssPhpOutputStyle($formatter)
+    {
+        return \ScssPhp\ScssPhp\OutputStyle::fromString($this->normalizeFormatter($formatter));
+    }
+
+    /**
+     * @param string|null $formatter
+     *
+     * @return \Bugo\SCSS\Style
+     */
+    protected function normalizeBugoOutputStyle($formatter)
+    {
+        return $this->normalizeFormatter($formatter) === 'compressed'
+            ? \Bugo\SCSS\Style::COMPRESSED
+            : \Bugo\SCSS\Style::EXPANDED;
+    }
+
+    /**
+     * Maps legacy formatter names from scssphp 1.x to the output styles
+     * supported by the modern compilers.
+     *
+     * @param string|null $formatter
+     *
+     * @return string
+     */
+    protected function normalizeFormatter($formatter)
+    {
+        $formatter = ltrim((string) $formatter, '\\');
+
+        $formatters = [
+            '' => 'expanded',
+            'expanded' => 'expanded',
+            'compressed' => 'compressed',
+            'ScssPhp\ScssPhp\Formatter\Expanded' => 'expanded',
+            'ScssPhp\ScssPhp\Formatter\Nested' => 'expanded',
+            'ScssPhp\ScssPhp\Formatter\Compact' => 'expanded',
+            'ScssPhp\ScssPhp\Formatter\Compressed' => 'compressed',
+            'ScssPhp\ScssPhp\Formatter\Crunched' => 'compressed',
+        ];
+
+        if (!isset($formatters[$formatter])) {
+            throw new \InvalidArgumentException(sprintf('Invalid scss formatter %s!', $formatter));
+        }
+
+        return $formatters[$formatter];
+    }
+
+    /**
+     * Sets the formatter for scss compilers.
      *
-     * Five formatters are included with scssphp/scssphp:
-     * - ScssPhp\ScssPhp\Formatter\Expanded
-     * - ScssPhp\ScssPhp\Formatter\Nested (default)
-     * - ScssPhp\ScssPhp\Formatter\Compressed
-     * - ScssPhp\ScssPhp\Formatter\Compact
-     * - ScssPhp\ScssPhp\Formatter\Crunched
+     * `scssphp/scssphp` 2.x and `bugo/scss-php` support `expanded` and `compressed`
+     * output styles. Legacy formatter class names from scssphp 1.x are also
+     * accepted and mapped to the closest supported output style.
      *
      * @link https://scssphp.github.io/scssphp/docs/#output-formatting
      *