Support additional load paths (#37)

* Support additional load paths

* Add an empty commit to rebuild CI

* [docs]: Rewrite header in capitalized style

* Add an empty commit to rebuild CI again

---------

Co-authored-by: bocharsky-bw <[email protected]>

Author: squrious

doc/index.rst

@@ -205,6 +205,9 @@ You can configure most of the `Dart Sass CLI options <https://sass-lang.com/docu
             # Emit a @charset or BOM for CSS with non-ASCII characters. Defaults to true in Dart Sass.
             # charset: true
 
+            # Register additional load paths. Defaults to empty array.
+            # load_path: []
+
             # Wether to generate source maps. Defaults to true when "kernel.debug" is true.
             # source_map: true
 
@@ -236,3 +239,24 @@ This bundle already installed for you the right binary. However, if you already
 
     symfonycasts_sass:
         binary: 'node_modules/.bin/sass'
+
+Register Additional Load Paths
+------------------------------
+
+You can provide additional `load paths <https://sass-lang.com/documentation/at-rules/use/#load-paths>`_ to resolve modules with the ``load_path`` option.
+
+For example, an alternative way to use Bootstrap would be to register the vendor path:
+
+.. code-block:: yaml
+
+    # config/packages/symfonycasts_sass.yaml
+    symfonycasts_sass:
+        sass_options:
+            load_path:
+                - '%kernel.project_dir%/vendor/bootstrap/scss'
+
+And then import bootstrap from ``app.scss`` with:
+
+.. code-block:: scss
+
+    @import 'bootstrap';

src/DependencyInjection/SymfonycastsSassExtension.php

@@ -112,6 +112,11 @@ public function getConfigTreeBuilder(): TreeBuilder
                             ->info('Embed source map contents in CSS.')
                             ->defaultValue('%kernel.debug%')
                         ->end()
+                        ->arrayNode('load_path')
+                            ->info('Additional load paths')
+                            ->scalarPrototype()
+                                ->end()
+                        ->end()
                         ->booleanNode('quiet')
                             ->info('Don\'t print warnings.')
                         ->end()

src/SassBuilder.php

@@ -25,6 +25,7 @@ class SassBuilder
         '--style' => 'expanded',                // Output style.  [expanded (default), compressed]
         '--[no-]charset' => null,               // Emit a @charset or BOM for CSS with non-ASCII characters.
         '--[no-]error-css' => null,             // Emit a CSS file when an error occurs.
+        '--load-path' => null,                  // Additional load paths
         // Source Maps
         '--[no-]source-map' => true,            // Whether to generate source maps. (defaults to on)
         '--[no-]embed-sources' => null,         // Embed source file contents in source maps.
@@ -123,7 +124,7 @@ public function getScssCssTargets(): array
     }
 
     /**
-     * @param array<string, bool|string> $options
+     * @param array<string, bool|array|string> $options
      *
      * @return list<string>
      */
@@ -147,6 +148,13 @@ public function getBuildOptions(array $options = []): array
                 $buildOptions[] = $option.'='.$value;
                 continue;
             }
+            // --load-path
+            if (\is_array($value)) {
+                foreach ($value as $item) {
+                    $buildOptions[] = $option.'='.$item;
+                }
+                continue;
+            }
             // --update
             // --watch
             if ($value) {
@@ -182,7 +190,7 @@ private function createBinary(): SassBinary
      *
      * Options are converted from PHP option names to CLI option names.
      *
-     * @param array<string, bool|string> $options
+     * @param array<string, bool|array|string> $options
      *
      * @see getOptionMap()
      */

tests/ConfigurationTest.php

@@ -66,6 +66,7 @@ public function testSassOptionsAreSet(): void
                     'embed_sources' => true,
                     'embed_source_map' => true,
                     'error_css' => true,
+                    'load_path' => ['foo'],
                     'quiet' => true,
                     'quiet_deps' => true,
                     'stop_on_error' => true,
@@ -82,6 +83,7 @@ public function testSassOptionsAreSet(): void
                     'embed_sources' => false,
                     'embed_source_map' => false,
                     'error_css' => false,
+                    'load_path' => [],
                     'quiet' => false,
                     'quiet_deps' => false,
                     'stop_on_error' => false,
@@ -102,6 +104,7 @@ public function testSassOptionsAreNullable(): void
                     'embed_sources' => null,
                     'embed_source_map' => null,
                     'error_css' => null,
+                    'load_path' => null,
                     'quiet' => null,
                     'quiet_deps' => null,
                     'stop_on_error' => null,

tests/SassBuilderTest.php

@@ -97,6 +97,22 @@ public function testEmbedSources(): void
         $this->assertStringContainsString('color:%20$color;', $result);
     }
 
+    public function testLoadPaths(): void
+    {
+        $builder = $this->createBuilder('app_using_external.scss', [
+            'load_path' => [
+                __DIR__.'/fixtures/external',
+            ],
+        ]);
+
+        $process = $builder->runBuild(false);
+        $process->wait();
+
+        $this->assertTrue($process->isSuccessful(), $process->getOutput());
+        $this->assertFileExists(__DIR__.'/fixtures/assets/dist/app_using_external.output.css');
+        $this->assertStringContainsString('color: red;', file_get_contents(__DIR__.'/fixtures/assets/dist/app_using_external.output.css'));
+    }
+
     public function testSassOptions(): void
     {
         $builder = new SassBuilder(
@@ -253,5 +269,16 @@ public static function provideSassPhpOptions()
                 '--no-trace',
             ],
         ];
+        yield 'Array options are expanded' => [
+            [
+                'style' => null,
+                'load_path' => ['foo', 'bar'],
+                'source_map' => null,
+            ],
+            [
+                '--load-path=foo',
+                '--load-path=bar',
+            ],
+        ];
     }
 }

tests/fixtures/assets/app_using_external.scss

@@ -0,0 +1,5 @@
+@use "partial";
+
+p {
+  color: partial.$color;
+}

tests/fixtures/external/_partial.scss

@@ -0,0 +1 @@
+$color: red;