Back to list
Jürgen Schwind 18 Feb 2026 PHP, CSS, Performance, Bootstrap, Composer, Optimization
css-purger: Remove unused CSS with PHP — lean, fast, controllable

css-purger: Remove unused CSS with PHP — lean, fast, controllable

Why css-purger?

If you work with Bootstrap or other large CSS libraries, you know the issue: your final build

often ships much more CSS than your pages actually need. That impacts loading time, hurts metrics,

and makes maintenance harder.

css-purger is a deliberately lightweight PHP

library built for exactly this use case: remove unused CSS rules from a stylesheet based on an

explicit selector allowlist.

What does css-purger do?

  • Removes unused CSS rules based on selectors you define
  • Supports nested blocks (e.g. @media)
  • Supports selectors with pseudo classes like :hover and :focus
  • Outputs either readable or minified CSS
  • Can be extended via your own subclasses
  • No additional external runtime required

Important: css-purger intentionally stays lightweight and does not aim to be a full CSS AST parser.

It uses efficient string-based logic.

Installation

composer require jbsnewmedia/css-purger

Practical Bootstrap example

use JBSNewMedia\CssPurger\Vendors\Bootstrap;

$purger = new Bootstrap('./assets/css/bootstrap.css');

$purger->loadContent();
$purger->prepareContent();
$purger->runContent();

$purger->addSelectors([
    ':root',
    '[data-bs-theme=light]',
    '[data-bs-theme=dark]',
    'body',
    'h1',
    '.h1',
    '.container',
    '.pt-3',
    '.pb-3',
    '.alert',
    '.alert-danger',
    '.btn:hover',
]);

file_put_contents('./assets/css/bootstrap-purged.css', $purger->generateOutput(false));
file_put_contents('./assets/css/bootstrap-purged.min.css', $purger->generateOutput());

This gives you a readable output for review and a minified production file for deployment.

Workflow recommendation from practice

  1. Start with a conservative selector set (layout, typography, core components).
  2. Add dynamic states explicitly (:hover, :focus, .show, .active, etc.).
  3. Verify the readable output during development.
  4. Use the minified output in production.

In Symfony projects with clear templates, this approach is easy to control because you explicitly

define what must stay.

Limits you should know

  • No fully automatic extraction of every selector from templates/JS
  • No complete CSS parser engine
  • The selector list must be maintained intentionally

That same explicitness is also its strength: you keep full control over final CSS size.

Conclusion

css-purger is a pragmatic tool for teams that want to reduce CSS overhead without introducing a

heavy build chain. Especially in PHP and Symfony setups, it can produce measurable wins quickly:

smaller files, less overhead, better loading times.

Links