All features

Cherry Blossom feature

Frontend Scss: Compiler

Compiles a theme SCSS entry point and writes its CSS counterparts.

Compiles a theme SCSS entry point and writes its CSS counterparts.

Capabilities and extension points

Compiles a theme SCSS entry point and writes its CSS counterparts.

The enqueue system normally creates this object through {@see \Cherry\Blossom\Frontend\SCSS::compile_enqueue()}. Developers can also use it directly when they need to compile a registered or custom entry point:

$compiler = new Compiler( 'public/scss/main.scss', [ 'autoprefixer' => true ] );

$compiler->compile()->write_to_file();

Active-theme entry points and nested imports use per-file child-theme resolution. Explicitly parent-owned entry points and imports remain in the parent theme.

Compilation and writing are deliberately separate. Call {@see compile()} to keep the result in memory, or chain {@see write_to_file()} to update the CSS and minified CSS files in the active or explicitly selected parent theme.

Compiled, formatted CSS.

  • var string

Compiled, minified CSS.

  • var string

Raw scssphp compilation result.

  • var \ScssPhp\ScssPhp\CompilationResult

Reserved SCSS root path.

  • var string

Whether the entry point and generated output are parent-owned.

  • var bool

Destination path for the formatted CSS file.

  • var string

Compiler instance used for this entry point.

A compiler is kept per wrapper instance so public and admin compilation cannot leak import paths or configuration into each other.

  • var SCSS_Compiler

Whether compiled CSS should be passed through the autoprefixer.

  • var bool

Sets up an SCSS compilation job.

The path is relative to the theme root, such as `public/scss/main.scss` or `admin/scss/editor.scss`. The default output mirrors that path beneath the active theme with `scss` replaced by `css`. Parent-owned jobs mirror it beneath the parent theme instead. Constructing the object does not compile or write files.

  • param string $path SCSS entry-point path relative to the theme root.
  • param array<string, mixed> $args Compilation arguments. Supports `autoprefixer` and `location_is_parent`.

Converts a theme-relative SCSS location to its CSS counterpart.

Use this method whenever code needs to locate the generated output for an SCSS entry point. Keeping this mapping in one place prevents compilation, change detection, and enqueue resolution from selecting different files.

  • param string $location Theme-relative SCSS location.
  • return string Theme-relative CSS location.

Gets the default absolute output path for an SCSS entry point.

Generated files normally belong to the active theme, allowing a child theme to contain the compiled result even when its entry point comes from the parent. Explicitly parent-only locations instead remain in the parent so their compiled path and enqueued URL cannot diverge.

  • param string $location Theme-relative SCSS location.
  • param bool $location_is_parent Whether the location is explicitly parent-only.
  • return string Absolute CSS output path.

Sets the formatted CSS destination path.

Developers rarely need to call this directly. Use it before {@see write_to_file()} when a compilation job must write outside the mirrored `public/css` or `admin/css` location. The `cherry/blossom/scss/output_path` filter can change the destination for all jobs without replacing the compiler class.

  • param string $path Absolute CSS destination path.

Filters the destination path for compiled CSS.

  • param string $path Absolute CSS destination path.

Compiles the configured SCSS entry point into memory.

Active-theme entry points use WordPress theme-file resolution. Parent-owned entry points resolve directly from the parent. Nested imports are handled by {@see Theme_Importer} with the corresponding import-path policy. Autoprefixing runs automatically when enabled in the constructor arguments.

This method does not write files. Chain {@see write_to_file()} when the generated CSS should be persisted.

  • return self Current compiler wrapper for method chaining.
  • throws \RuntimeException When the configured entry point cannot be read.

Creates formatted and minified autoprefixed CSS variants.

This is called automatically by {@see compile()} when autoprefixing is enabled. Call it directly only when a subclass has deliberately changed the in-memory `$css` after compilation and needs to regenerate both output variants.

Creates the minified autoprefixed CSS variant.

  • return self Current compiler wrapper for method chaining.

Creates the formatted autoprefixed CSS variant.

  • return self Current compiler wrapper for method chaining.

Initialises an autoprefixer for arbitrary CSS.

This method is currently a reserved extension point and does not modify the compiler output. Use {@see apply_autoprefix()} to process the CSS generated by this compiler.

  • param string $css CSS to process.
  • param bool $minify Whether the requested result should be minified.

Gets the entry-point path without its public or admin SCSS prefix.

This is useful when a developer needs a stable filename such as `main.scss` or `blocks/faq-toggle.scss` for logging, cache keys, or custom output mapping.

  • return string Entry-point path relative to its SCSS source root.

Writes the compiled CSS and its minified counterpart to disk.

Call {@see compile()} first. An empty result is ignored. The destination directory is created when needed, making this safe for new nested entry points such as `public/scss/blocks/example.scss`.

  • return self Current compiler wrapper for method chaining.

Fires after all generated files for this job have been written.

  • param array $paths Absolute paths of the written files.
  • param Compiler $compiler Current compilation job.

Creates the CSS destination directory when it does not exist.

Stages complete generated files before replacing their public destinations.

  • param array $outputs Generated content keyed by absolute output path.

Writes the minified CSS alongside the formatted CSS file.

The destination uses the configured output path with `.min.css` as its suffix. Nothing is written when no minified variant was generated, such as when autoprefixing was disabled.

  • return self Current compiler wrapper for method chaining.

Gets the minified output path for the configured CSS destination.

  • return string Absolute minified CSS output path.

Gets the underlying scssphp compiler for this entry point.

The compiler is created lazily and configured once. Developers integrating with scssphp should generally prefer the setup actions in {@see setup_compiler()} instead of mutating the returned object after a compilation has already begun.

  • return SCSS_Compiler Configured scssphp compiler instance.

Configures the underlying scssphp compiler.

Use `cherry/blossom/scss/setup_compiler/before` for settings that must be applied before Cherry Blossom registers its import paths. Use the `after` action for settings that should take precedence over the defaults.

Fires before Cherry Blossom configures the scssphp compiler.

  • param SCSS_Compiler $compiler scssphp compiler instance.

Fires after Cherry Blossom configures the scssphp compiler.

  • param SCSS_Compiler $compiler scssphp compiler instance.

Gets the ordered SCSS roots used for per-file import resolution.

Active-theme frontend compilation checks the child public SCSS root before its parent. Active-theme admin compilation checks both admin roots, then both public roots. Parent-owned jobs use parent roots only.

Developers can append project-specific source roots with the `cherry/blossom/scss/import_paths` filter. Preserve the existing order when child-theme overrides should retain priority.

  • return string[] Absolute SCSS source directories in resolution order.

Filters the ordered SCSS import roots.

  • param string[] $paths Absolute SCSS source directories.
  • param self $compiler Current compiler wrapper.

Source reference

This editable reference page is based on the PHP documentation in frontend/scss/class-compiler.php.