PHPuncss

Remove unused CSS rules from stylesheets using pure PHP.

Installation

composer require globusstudio/phpuncss

Quick Start

use GLOBUSstudio\PHPuncss\Uncss;

(new Uncss())
    ->styleSheets(__DIR__ . '/css/*.css')
    ->htmlFiles(__DIR__ . '/templates/**/*.html')
    ->setFilenameSuffix('.clean')
    ->refactor()
    ->saveFiles();

Modes

Basic - Fast, weak matching (recommended for most cases)

$uncss = new GLOBUSstudio\PHPuncss\Uncss();

Advanced - Slower, DOM-aware matching (more accurate)

$uncss = new GLOBUSstudio\PHPuncss\UncssAdvanced();

Key Methods

// Required
->styleSheets('path/to/*.css')       // CSS files (glob supported)
->htmlFiles('path/to/**/*.html')     // HTML/templates (glob supported)
->refactor()                         // Execute optimization

// Output
->saveFiles()                        // Save to disk
->returnAsText()                     // Get as array

// Optional
->setFilenameSuffix('.min')          // Default: '.min' ⚠️ Without this, overwrites originals!
->whitelist('.class', '#id')         // Preserve specific selectors
->setMaxFileSize(10 * 1024 * 1024)   // Limit: 10MB (default)
->skipComment()                      // Remove header comment
->disableLogging()                   // Disable logging

Logging

Memory (default)

$uncss->refactor()->saveFiles();
print_r($uncss->getLogs());

File

use GLOBUSstudio\PHPuncss\Logger\FileLogger;

$uncss->setLogger(new FileLogger('./logs/uncss.log'));

Examples

Laravel + Bootstrap

use GLOBUSstudio\PHPuncss\Uncss;

(new Uncss())
    ->whitelist('.modal-backdrop', '.fade', '.show', '.collapse')
    ->styleSheets(public_path('css/app.css'))
    ->htmlFiles(resource_path('views/**/*.blade.php'))
    ->setFilenameSuffix('.purged')
    ->refactor()
    ->saveFiles();

CI/CD

use GLOBUSstudio\PHPuncss\Uncss;
use GLOBUSstudio\PHPuncss\Logger\FileLogger;

try {
    (new Uncss())
        ->setLogger(new FileLogger('./logs/optimization.log'))
        ->styleSheets('./dist/css/*.css')
        ->htmlFiles('./dist/**/*.html')
        ->setFilenameSuffix('.min')
        ->setMaxFileSize(100 * 1024 * 1024)
        ->refactor()
        ->saveFiles();
    
    exit(0);
} catch (Exception $e) {
    echo "Error: {$e->getMessage()}\n";
    exit(1);
}

WordPress

use GLOBUSstudio\PHPuncss\Uncss;

(new Uncss())
    ->whitelist('.wp-block-*', '.alignleft', '.alignright')
    ->styleSheets(get_template_directory() . '/assets/css/*.css')
    ->htmlFiles(get_template_directory() . '/**/*.php')
    ->setFilenameSuffix('.opt')
    ->refactor()
    ->saveFiles();

Important Notes

• Without setFilenameSuffix() - original files will be overwritten
• Advanced mode - slower, not always accurate with dynamic templates
• JavaScript CSS - cannot detect CSS added/used only via JavaScript
• Whitelist dynamic classes - always whitelist JS-generated selectors
• Test first - use returnAsText() to preview before saveFiles()

Requirements

PHP 8.0+

License

MIT - LICENSE.md

GLOBUS.studio - https://globus.studio © 2020-2025 GLOBUS.studio. All rights reserved.