tomdazy/php-scss-compiler

Simple and lightweight SCSS compiler and watcher for PHP 8 using scssphp.

v1.0.2 2026-04-12 18:16 UTC

Requires

• php: ^8.1
• scssphp/scssphp: ^2.1

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• php
• sass
• scss
• compiler
• scssphp
• watcher

README

Ce projet a pour but de proposer une solution simple et légère de compiler les fichiers SCSS en PHP v8.

Il s'appuie sur scssphp et fournit deux modes d'exécution :

• build : compile une fois tous les fichiers configurés
• watch : surveille les fichiers SCSS et recompile automatiquement en cas de modification

Le package a été pensé pour être facile à intégrer dans des projets PHP qui ne veulent pas dépendre d'une toolchain Node.js.

Fonctionnalités

• configuration simple via un fichier PHP
• support des fichiers, dossiers et patterns glob
• support récursif des dossiers
• destination configurable par entrée
• exclusion optionnelle des partials (_*.scss)
• sortie CSS compressée ou lisible
• suivi basique des dépendances locales (@import, @use, @forward)
• exécutable CLI prêt à l'emploi via vendor/bin/scss-builder

Installation

Depuis Packagist

composer require tomdazy/php-scss-compiler

En local

composer install

Configuration

Crée un fichier scss.config.php dans ton projet.

Tu peux partir de l'exemple fourni dans config/scss.config.example.php.

Exemple minimal

<?php

declare(strict_types=1);

return [
    'style' => 'compressed',
    'watch_interval' => 1.0,
    'compile_on_start' => true,
    'verbose' => true,
    'entries' => [
        [
            'sources' => [
                __DIR__ . '/assets/scss',
            ],
            'destination' => __DIR__ . '/public/css',
            'recursive' => true,
            'include_partials' => false,
        ],
    ],
];

Utilisation

Build

vendor/bin/scss-builder build scss.config.php

Watch

vendor/bin/scss-builder watch scss.config.php

Si aucun fichier de configuration n'est fourni, le binaire cherche par défaut scss.config.php dans le dossier courant.

Structure de configuration

Le fichier de configuration doit retourner un tableau avec les clés suivantes :

• style : compressed ou expanded
• watch_interval : intervalle de surveillance en secondes
• compile_on_start : compile immédiatement au démarrage du mode watch
• verbose : active les logs
• entries : liste des entrées à compiler

Chaque entrée accepte :

• sources : tableau de fichiers, dossiers ou patterns
• destination : dossier de sortie, ou fichier CSS si une seule source fichier est utilisée
• recursive : parcours récursif si la source est un dossier
• include_partials : compile aussi les partials _*.scss

Exemples d'entrées

Plusieurs fichiers vers un dossier

[
    'sources' => [
        __DIR__ . '/assets/scss/app.scss',
        __DIR__ . '/assets/scss/admin.scss',
    ],
    'destination' => __DIR__ . '/public/css',
]

Un fichier vers un fichier précis

[
    'sources' => [
        __DIR__ . '/assets/scss/landing.scss',
    ],
    'destination' => __DIR__ . '/public/css/landing.bundle.css',
]

Un dossier récursif

[
    'sources' => [
        __DIR__ . '/modules',
    ],
    'destination' => __DIR__ . '/public/modules-css',
    'recursive' => true,
    'include_partials' => false,
]

Développement

composer install
composer test
vendor/bin/scss-builder build config/scss.config.example.php

Philosophie

• simple
• lisible
• portable
• facile à embarquer dans un projet PHP
• sans surcouche inutile

Licence

MIT