PHP: Class 'Phar' not found

PHP: Class 'Phar' not found

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

PHP: Class 'Phar' not found

When deploying a Silex application packaged as a .phar archive, encountering the Fatal error: Class 'Phar' not found is almost exclusively a configuration mismatch rather than a missing library. The error message points to line 11 of silex.phar, but the root cause lies in how PHP discovers and loads extensions at runtime.

The user has verified that extension=phar.so is present in /etc/php/php.ini and that the file exists at /usr/lib/php/modules/phar.so. They have also set phar.readonly = Off and phar.require_hash = Off, which are necessary for manipulating PHAR files, not for loading them. Despite this, the class remains undefined. This discrepancy usually stems from one of three scenarios: the specific PHP-FPM or CLI process isn't reading the correct php.ini, the extension is compiled but not enabled in that specific environment, or the web server is serving a file that isn't actually a valid PHAR bundle.

Verifying Extension Loading Contexts

PHP installations often support multiple SAPIs (Server Application Interfaces), such as CLI, CGI, FPM, and Apache modules. Each of these can have its own configuration file. If you edited /etc/php/php.ini, you must ensure that the specific process handling your web request is using it.

For example, on many Debian-based systems, PHP-FPM uses /etc/php/8.x/fpm/php.ini, while CLI uses /etc/php/8.x/cli/php.ini. The extension path might also differ between these directories. You can verify which configuration file is currently active by running:

php -i | grep "Loaded Configuration File"

If the output shows a different path than where you added extension=phar.so, that file needs updating. Alternatively, check if the extension was compiled in dynamically but not enabled. Run the following command to see all loaded extensions:

php -m | grep phar

If phar does not appear in the list despite the line existing in your config, you likely need to restart the web server or PHP-FPM service after making changes. A simple systemctl restart php8.1-fpm (adjusting the version as needed) is often required for FPM pools to pick up new configurations.

The Case of Missing or Corrupt PHAR Files

Sometimes the configuration is correct, but the file itself is not being recognized as a PHAR archive. PHP requires strict validation when opening .phar files. If the file was created incorrectly, renamed from a non-PHAR source without proper repacking, or if the web server is serving it with the wrong MIME type (e.g., text/plain instead of application/x-phar), PHP might fail to initialize the PHAR class.

Ensure that your .htaccess or Nginx/Apache configuration serves PHAR files with the appropriate header:

AddType application/x-phar .phar

In Apache, if you are using mod_php directly, ensure that php_flag display_errors on; is set temporarily to see more verbose error messages if the class loading fails for a reason other than the extension being missing. However, note that this only helps debugging; it does not fix the underlying issue if the extension isn't loaded.

Trade-offs in Using PHAR Archives

While PHAR files offer a convenient way to distribute self-contained applications, they introduce deployment complexity. Unlike standard Composer-managed projects where dependencies are autoloaded via vendor/autoload.php, a PHAR archive bundles everything into a single binary. This means that any internal PHP version mismatches or missing extensions within the bundled environment can lead to subtle runtime errors like the one described.

If you are building a Silex application, consider whether you truly need to distribute it as a .phar. For many production environments, deploying via Composer and running under standard autoloading is more maintainable and easier to debug. PHAR files shine in scenarios where you need to distribute a fully isolated tool or script that doesn't rely on system-wide PHP configurations.

Final Check: Rebuilding the Archive

If all configuration checks pass, there is a chance the .phar file itself was not built correctly. A common mistake is using phar:// wrappers incorrectly or including files that reference relative paths that break in the PHAR context. Always rebuild your archive using the official phar CLI tool to ensure compatibility:

phar -v create app.phar index.php
# then add other files
phar -v add app.phar vendor/

By ensuring the extension is loaded, the SAPI matches the configuration, and the file is a valid PHAR bundle, you can avoid the Class 'Phar' not found error entirely.

Our network