PHP-CSS-Parser Incompatible with OPCache / Composer Autoload

[dinobot71]

Hi, after several hours of trying to resolve this issue by cleaning/re-installing various parts of my system (and obviously reinstalling vendor/) I am unable to get this package working within a PHP-FPM/Apache backend. It consistently generates a fatal exception reproducible in the same place every time. It appears to be not be working propertly with autoload and OPCache.

When I use the package in a CLI environment (no OPCache involved)...there is no issue.

The exception I'm seeing:

[BOOT] Starting PHP-FPM (Background)...


[Preloader] init...
[Preloader] loading...
[Preloader] Preloaded 2151 classes
[Preloader] complete.
[25-Feb-2026 04:50:23] NOTICE: fpm is running, pid 42
[25-Feb-2026 04:50:23] NOTICE: ready to handle connections

[BOOT] php-fpm is RUNNING.

[BOOT] Starting Apache (Foreground)...
...
...
- -  25/Feb/2026:04:50:27 +0000 "GET /backend.php" 200 //var/www/html/backend.php 481.192 2048 4.16%

NOTICE: PHP message: Exception [/var/www/html/vendor/thecodingmachine/safe/generated/Exceptions/ClassobjException.php: 9]: Cannot redeclare class Sabberworm\CSS\Rule\Rule (previously declared in /var/www/html/vendor/sabberworm/php-css-parser/src/Property/Declaration.php:27)

Traceback: 
#0 /var/www/html/vendor/thecodingmachine/safe/generated/8.1/classobj.php(19): Safe\Exceptions\ClassobjException::createFromPhpError()
#1 /var/www/html/vendor/sabberworm/php-css-parser/src/Rule/Rule.php(14): Safe\class_alias('Sabberworm\\CSS\\...', 'Sabberworm\\CSS\\...')
#2 /var/www/html/vendor/composer/autoload_real.php(41): require('/var/www/html/v...')
#3 /var/www/html/vendor/composer/autoload_real.php(45): {closure:ComposerAutoloaderInita513f45a21088ff88ff9a0ececb2b3ac::getLoader():37}('0174385c3be07e8...', '/var/www/html/v...')
#4 /var/www/html/vendor/autoload.php(22): ComposerAutoloaderInita513f45a21088ff88ff9a0ececb2b3ac::getLoader()
#5 /var/www/html/backend.php(21): require('/var/www/html/v...')

#6 {main}

The problem seems to be this class and its declarations...the way its working with thecodingmachine/safe package.

php-css-parser/src/Rule

Unfortunately I can not simply disable OPCache, I have to continue using it. So my only option would seem to be to wrap the usage of this package (via dompdf...I'm generated pdf files), into a CLI script that I would literally exec() from the PHP backend endpoint.

That seems to me to be a terrible solution...this package should not break and "poison" everything else. Its not breaking when I use it, it breaking when my backend loads up the standard autoload file.

In fact, if I remove a few lines from the autoload files (fgrep sabb in autoload/composer):

autoload_files.php:    '0174385c3be07e86008907d06ee66531' => $vendorDir . '/sabberworm/php-css-parser/src/Rule/Rule.php',
autoload_files.php:    '98aea6e41b9cb79b379b10f37ba1f0b7' => $vendorDir . '/sabberworm/php-css-parser/src/RuleSet/RuleContainer.php',
autoload_psr4.php:    'Sabberworm\\CSS\\' => array($vendorDir . '/sabberworm/php-css-parser/src'),
autoload_static.php:        '0174385c3be07e86008907d06ee66531' => __DIR__ . '/..' . '/sabberworm/php-css-parser/src/Rule/Rule.php',
autoload_static.php:        '98aea6e41b9cb79b379b10f37ba1f0b7' => __DIR__ . '/..' . '/sabberworm/php-css-parser/src/RuleSet/RuleContainer.php',
autoload_static.php:            0 => __DIR__ . '/..' . '/sabberworm/php-css-parser/src',
installed.json:                "sabberworm/php-css-parser": "^8.4 || ^9.0"
installed.json:            "name": "sabberworm/php-css-parser",
installed.json:            "homepage": "https://www.sabberworm.com/blog/2010/6/10/php-css-parser",
installed.json:            "install-path": "../sabberworm/php-css-parser"
installed.php:        'sabberworm/php-css-parser' => array(
installed.php:            'install_path' => __DIR__ . '/../sabberworm/php-css-parser',

the problem goes away...If I remove those 4 Rule and RuleSet files from the composer autoload files...the problem goes away.

autoload_files.php:    '0174385c3be07e86008907d06ee66531' => $vendorDir . '/sabberworm/php-css-parser/src/Rule/Rule.php',
autoload_files.php:    '98aea6e41b9cb79b379b10f37ba1f0b7' => $vendorDir . '/sabberworm/php-css-parser/src/RuleSet/RuleContainer.php',
autoload_static.php:        '0174385c3be07e86008907d06ee66531' => __DIR__ . '/..' . '/sabberworm/php-css-parser/src/Rule/Rule.php',
autoload_static.php:        '98aea6e41b9cb79b379b10f37ba1f0b7' => __DIR__ . '/..' . '/sabberworm/php-css-parser/src/RuleSet/RuleContainer.php',

I didn't do any kind of weird installation here, just standard composer setup, and then "composer install" with an empty vendor folder.

Somehow, this package and/or its interaction with thecodingmachine/safe stuff...is injecting those 4 files into the autoload files...which in turn is causing "double loads" of the files, and then PHP barfs with a critical exception...which kills my backend :(

I would really like to continue using dompdf, but having to walk on eggshells and wrap it into external CLI script is terrible hack in my view. Not to mention all the performance I'll be losing everytime is runs externally and has to reload every single file, making the endpoint for my PDFs that much slower. :(

The other hack here is to just edit the autoload files per above, but again, this seems like a terrible hack. Having to hack files out of an automated step of composer...for one package is not really sustainable. How do I know what other classes will be an issue? But, at least performance is still reasonably good.

Is there any better work around available? I'm using the latest stable stuff, I don't have weird versions of anything installed. As I say, when I run my PDF generation outside of the Apache/PHP-FPM/OPCache environment...everything works complete fine...and also of course, when I edit the composer autoload files.

Note also that my preload file does NOT preload either this packge or the thecodingmachine stuff. Its being loaded directly by the composer autoload files. There is some kind of interaction here that is poisoning the autoload system. All you need to reproduce this is:

require dirname(__FILE__) . '/vendor/autoload.php';

For my composer file, the requirements I have:

  "require": {
    "bshaffer/oauth2-server-php":           "~1.8",
    "bshaffer/oauth2-server-httpfoundation-bridge": "v1.2",
    "lcobucci/jwt":                         "*",
    "firebase/php-jwt":                     "*",
    "monolog/monolog":                      "*",
    "nesbot/carbon":                        "*",
    "sabre/xml":                            "*",
    "guzzlehttp/guzzle":                    "*",
    "symfony/yaml":                         "*",
    "symfony/psr-http-message-bridge":      "*",
    "symfony/process":                      "*",
    "symfony/mailer":                       "*",
    "symfony/mailgun-mailer":               "*",
    "symfony/sendgrid-mailer":              "*",
    "symfony/google-mailer":                "*",
    "league/route":                         ">=6.2.0",
    "laminas/laminas-diactoros":            "*",
    "laminas/laminas-httphandlerrunner":    "*",
    "league/container":                     "*",
    "peppeocchi/php-cron-scheduler":        "*",
    "php":                                  ">=8.4",
    "opis/closure":                         ">=4.3.1",
    "erusev/parsedown":                     "*",
    "illuminate/database":                  "^12.10",
    "illuminate/events":                    "^12.10",
    "illuminate/bus":                       "^12.10",
    "illuminate/collections":               "^12.10",
    "illuminate/broadcasting":              "^12.10",
    "illuminate/support":                   "^12.10",
    "illuminate/contracts":                 "^12.10",
    "illuminate/queue":                     "^12.10",
    "illuminate/container":                 "^12.10",
    "ramsey/uuid":                          "4.7.5",
    "studio24/rotate":                      "*",
    "ext-json":                             "*",
    "ext-zlib":                             "*",
    "ext-pdo":                              "*",
    "ext-sqlite3":                          "*",
    "phpfastcache/phpfastcache":            "*",
    "ext-curl":                             "*",
    "salsify/json-streaming-parser":        "*",
    "dompdf/dompdf":                        "*",
    "dompdf/php-svg-lib":                   "*",
    "dompdf/php-font-lib":                  "*",
    "twig/twig":                            "*",
    "psr/log":                              "*",
    "ext-sockets":                          "*",
    "ext-zip":                              "*",
    "ext-gd":                               "*",
    "ext-imagick":                          "*",
    "ext-pcntl":                            "*",
    "ext-pgsql":                            "*",
    "ext-odbc":                             "*",
    "ext-calendar":                         "*",
    "ext-iconv":                            "*",
    "ext-fileinfo":                         "*",
    "ext-xml":                              "*",
    "ext-dom":                              "*"
  },

The other main clauses that maybe I have wrong in the composer file:

 "config": {
    "allow-plugins": {
      "kylekatarnls/update-helper": true
    }
  },
  "require-dev": {
    "phpunit/phpunit": "^12"
  }

Please let me know if a better work around is available. Dompdf seems to work really well, but I need it to work both for CLI and in a web server backend.

[dinobot71]

One followup, I tested the edited autoload files while doing a full CLI version of generating a PDF file with dompdf. Works fine :)

So, it seems like editing the autoload files works for both environments; doesn't matter to CLI but enables use with OPCache in web environment. As work arounds go, I really don't like it, but...it is a a work around. :) Would still like to see a better kind of fix here though.

[oliverklee]

@dinobot71 Have you cleared the OP cache after the update, e.g. using Cachetool? Does the problem then still occur?

(Please note that there are two OP caches: one for CLI and one for the webserver. Clearing the cache on the CLI does not clear the webserver OP cache and vice versa.)

[dinobot71]

Mmmmm, did not know that...let me investigate that part. For the web site; it seems really difficult to clear specific files; I tried using the OPCache blacklist file and with https://github.com/amnuts/opcache-gui I can see OPCache reporting the file as blocked...but then at the same time on the "Cached" tab, I can see the sabber* files ... being cached. When I looked around on the web about that, it seems like the blacklist files only says "don't accelerate these files"...it doesn't mean "don't cache them". ...and there is a file caching switch for OPCache...but if I disable that...its for all files :( ...and then...no point using OPCache :(

I did full resets (stop/start) of the web server; which in my cases is Apache => PH-FPM (so have to stop/start both). ...and I can see the effects of changing OPCache settings...but no matter what I did, OPCache was still bringing the sabber files in to its file cache. I can double check my preload script to see if maybe I did something there that is bringing in the files.

For the CLI side...I did not know there is caching there. Let me investigate that...would be nice to know for sure that both environments are acting the same way...or not.

[oliverklee]

Usually, the way to go is to clear all caches, not only a subset. (I use CacheTool in my projects to do that after deployment and haven't cleared the caches manually, though.)

[oliverklee]

And there seem to be multiple caches (according to the CacheTool README): APCu cache, OP cache and file status cache.

[dinobot71]

Thanks for the tip on Cachetool, it actually has features for digging into the PHP-FPM caching. That will be handy independent of this issue :)

This one looks like an easy / dumb fix though. I double checked my preload file, and yes, it was actually bringing in the sabber stuff, once I move it to my set of files files to ignore during preload...everything works fine. ...without hacking the autoload file :) There is definitely a negative interaction here; when those Rule files get added directly to the autoload files...yes it "can" cause problems, but only if you have a situation where you might be autoloading the classes involved more than once.

i.e. if you have preloading involved :(

But the chances of other users having this same intersection of usage? seems unlikely. The would have to explicitly try to preload the package to hit this problem. I double most users would. Its only going to impact people who are squeezing hard for performance.

I feel like you can close this and just add a warning somewhere for users not to preload the package...at least for this version. From what I saw in your code...I think there is a newer version on the way that uses the "declaration" mechanics in a different way. So it well be the case that the next version of your package doesn't even have this issue.

Give me a few minutes, and I'll see if I can give you a minimum way to reproduce the autoload file issues. With that in hand, we could then try different versions of your package to see which versions mess up the autoload files which ones don't. If the latest version doesn't...then you could just the performance folks to move forward their version.

[dinobot71]

Ok, minimum reproduction test:

1. create an empty directory
2. in the empty directory create the composer.json file (included below)
3. in the empty directory run "composer install"
4. If you now look in vendor/composer/* you can find the 4 "Rule" file additions which mess up autoloading if you are ALSO doing preloading.

The minimal composer.json to reproduce:

{
  "name": "test/test",
  "require": {
    "dompdf/dompdf":                        "*",                         
    "dompdf/php-svg-lib":                   "*",                         
    "dompdf/php-font-lib":                  "*",                
    "ext-json":                             "*",
    "ext-zlib":                             "*",
    "ext-pdo":                              "*",
    "ext-sqlite3":                          "*",
    "ext-curl":                             "*",
    "ext-sockets":                          "*",
    "ext-zip":                              "*",
    "ext-gd":                               "*",
    "ext-imagick":                          "*",
    "ext-pcntl":                            "*",
    "ext-pgsql":                            "*",
    "ext-odbc":                             "*",
    "ext-calendar":                         "*",
    "ext-iconv":                            "*",
    "ext-fileinfo":                         "*",
    "ext-xml":                              "*",
    "ext-dom":                              "*"
  },
  "version": "1.0.0",
  "config": {
    "allow-plugins": {
      "kylekatarnls/update-helper": true
    }
  },
  "require-dev": {
    "phpunit/phpunit": "^12"
  }
}

I'll try with some different versions of your package to see if it makes any difference.

[JakeQZ]

I'll try with some different versions of your package to see if it makes any difference.

The specific file autoloads were added in #1534 to allow PHPStan find the class_aliases that were recently added following moving/renaming of some classes. These changes were included in the recent 9.2 release. So I wouldn't expect a similar issue with the 9.1 or earlier releases, as they were not present then.

Using include_once rather than include in an autoloader may help (though the PHP docs example uses include).

[dinobot71]

latest version (dev-main) has the same issue. :(

So it seems the safest/simplest thing to do is just not preload this package. That easy enough for me to do. I'll close the ticket, but I think you guys should add a note somewhere to not preload this package because of the autoload impacts.

Note that I did double check my preloader to be sure it us using require_once() instead if require(). For sure it was using require_once(). This seems to be an impact that is out of the user's control - even using require_once()...this package will still create a fatal exception if it gets preloaded.

Flipping back to v9.1 might be a reasonable solution as well, but it sounds like this is just how the package works moving forward, so that would mean being locked to v9.1 forever. :(

Since I have the option of just not preloading it...I think that's the best option all things considered. I really do think you guys should document that this package is not preloading friendly.