包简介

This is a preprocessor for SCSS files to generate CSS files in Kirby. It uses the scssphp library https://scssphp.github.io/scssphp/. This Kirby plugin automatically processes SCSS files when they are changed. Optionally, you can use this Kirby plugin to generate 'Critical CSS'.

README 文档

README

The SCSSPHP plugin for Kirby creates the corresponding "*.css file" from a "*.scss file" and automatically integrates it into the invisible <HEAD> area of the website via the stylesheet link line <?php snippet('scss') ?>. The "*.scss file" can, of course, include any number of additional "*.scss files" using @import "..." in accordance with the Sass rules, which are also evaluated by the plugin.

The plugin can automatically detect whether one of the "*.scss files" used has been changed and then regenerates the "*.css file." Otherwise, only the stylesheet link line with the last generated "*.css file" is provided.

It is possible to create different SCSSs for each Kirby template. Just use the name of your template file for the SCSS file (e.g. article.scss for templates/article.php), and place it in assets/scss. If no SCSS file for a template can be found, default.scss will be used.

It is also possible to use a different SCSS file and/or for other media by adding another call such as "<?php snippet('scss', ['scss' => 'print', 'media' => 'print']); ?>" into the invisible <HEAD> area of the website code.

When the website is accessed by someone logged-in with the role of a admin, a detailed "*.css file" is used, which also links to the corresponding SourceMap. This detailed "*.css file" can be examined in detail in the browser, for example with <F12>. All other visitors receive a compressed "*.css file". You can change these roles in the config via the HeinerEF.scssphp.scssDeveloperRoles option.

Optionally you can use this Kirby plugin to generate 'critical CSS'. Please look at README_critical_CSS.md for details.

This Kirby plugin uses the SCSSPHP compiler https://github.com/scssphp/scssphp/ written in PHP, which was originally developed by Leaf Corcoran and is now maintained by Anthon Pang and Cédric Morin.

Installation

Download

Download the contents of this repository as Zip file.

Rename the extracted folder to heineref_scssphp and copy it into the site/plugins/ directory in your Kirby project. If it does not exist, create a new directory site/plugins/ first. This file README.md therefore receives the path site/plugins/heineref_scssphp/README.md.

Composer

composer require heineref/kirby-scssphp

Git submodule

If you have used git in your project before:

git submodule add https://github.com/heineref/kirby-scssphp.git site/plugins/heineref_scssphp

Setup

Make sure you backup your original CSS files beforehand.
Create a folder scss inside the /assets folder.
Create a file default.scss with some content and place it inside assets/scss.
Make sure the folder /assets/css exists on your server.
Add 'scssNestedCheck' => true to the config of your dev environment. Read more about multi environment setup for Kirby.
Call the SCSS snippet with <?php snippet('scss') ?> in your HTML <HEAD> area.

Using SCSS plugin

After installing and setting up this plugin, assets/css/*.css-files will be overwritten automatically.

Options

All options require HeinerEF.scssphp. as prefix.

scssNestedCheck

default: false
If true, the plugin checks if partials are changed. If any partial is newer than the main SCSS file, the main SCSS file will be 'touched'. This will trigger the SCSSPHP compiler, on this server and also an another environment when synced.
Look at "Setup 5." for details!

scssDeveloperRoles

default: ['admin']
Only these roles use the NOT minified CSS and can access the corresponding SourceMap.

scssDevelopment

default: false
If true, the CSS file is build EVERY time the SCSSPHP plugin runs

Compatibility

Sass is a CSS preprocessor language that adds many features such as variables, mixins, imports, nesting, color manipulation, functions, and control directives.

For a complete guide to the syntax of Sass, please consult the official documentation.

The new implementation v2.x of the SCSSPHP compiler is a port of dart-sass, making it spec-compliant and easier to update by their developers to support new Sass features. However the actual release does not implement Sass modules yet.

Note

Unlike previous implementations of the SCSSPHP plugin, you can now update the SCSSPHP compiler independently of the SCSSPHP plugin, e.g. using Composer, as long as the compiler calls and data transfer by the SCSSPHP compiler remain unchanged.

Please only update in your development environment!

Requirements

This plugin was built using Kirby 5.x and tested with Kirby 4.x.

It may work with earlier versions.

Otherwise, take a look at https://github.com/bartvandebiezen/kirby-v2-scssphp

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment.

License

MIT

It is not permitted to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any form of hate speech.

Credits

Leaf Corcoran et al. the SCSSPHP compiler written in PHP
Bart van de Biezen the initial Kirby Plugin
Jan-Frederik Stieler updated the Kirby Plugin to Kirby 3

heineref/kirby-scssphp 适用场景与选型建议

heineref/kirby-scssphp 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 13 次下载、GitHub Stars 达 0，最近一次更新时间为 2025 年 09 月 20 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「css」「scss」「stylesheet」「scssphp」「kirby-plugin」「kirby-cms」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 heineref/kirby-scssphp 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 heineref/kirby-scssphp 我们能提供哪些服务？

定制开发 / 二次开发

基于 heineref/kirby-scssphp 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 heineref/kirby-scssphp 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

jbzoo/less 4

PHP wrapper for any less-compilers

nerds-and-company/css-to-inline-styles-twig-extension 3

A Twig extension to insert css as inline styles with a tag

odan/twig-assets 22

Caching and compression for Twig assets (JavaScript and CSS).

hexydec/cssdoc 5

A token based CSS Document parser and minifier written in PHP

neilime/zf-assets-bundle 4

Zend Framework 3+ module that provides assets bundling / caching

codefareith/cf-beskin 0

Define your own css rule-sets for the TYPO3 CMS backend.

heineref/kirby-scssphp

包简介

关键字：