How to correctly use `.user.ini`-file in PHP?

How to correctly use `.user.ini`-file in PHP?

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

Stefan Bogdanescu

Founder & Senior Architect

Why .user.ini Settings Often Fail and How to Fix Them

Developers frequently encounter a frustrating scenario: you place a configuration file named .user.ini in your project directory, populate it with directives like display_errors=on, and expect those settings to take effect immediately. When the script runs, however, ini_get("display_errors") returns an empty string or ignores the directive entirely. This isn't usually a syntax error; it is almost always a misunderstanding of how PHP's per-user configuration system works in different environments.

The core issue lies in the distinction between the global php.ini, the SAPI-specific configuration, and the .user.ini mechanism. As demonstrated in typical debugging sessions, running php --ini often reveals that the CLI environment is loading a specific system-wide configuration file (e.g., /etc/php5/cli/php.ini) and scanning designated directories for additional .ini files. It does not automatically scan the current working directory for .user.ini.

The directive responsible for this behavior is user_ini.filename. In many installations, particularly on shared hosting or specific server configurations, this value defaults to something like .htaccess or is explicitly set to an empty string. If user_ini.filename is empty or points to a file that does not exist in your current directory, PHP will completely ignore any .user.ini files you create there. The configuration simply never gets loaded during the bootstrap process.

To correctly use .user.ini, you must first ensure that PHP is actually configured to look for it. There are two primary approaches to solving this, depending on whether you control the server environment or are running locally.

Verifying user_ini.filename

Before touching configuration files, inspect the current state of your PHP environment. Run the following command to see what filename PHP expects:

php -i | grep user_ini.filename

If the output shows an empty value or a default path that doesn't match your directory structure, the .user.ini file is being ignored by design. In a CLI environment without suPHP or specific hosting wrappers, the standard behavior often disables per-user configuration entirely to prevent security risks associated with arbitrary directory changes.

The Role of user_ini.cache_ttl

Another critical factor mentioned in debugging logs is user_ini.cache_ttl. This setting dictates how long PHP caches the parsed .user.ini file before re-reading it from disk. The default value is often 300 seconds (5 minutes). If you modify a .user.ini file and run your script immediately, you might see old values or empty values because PHP is serving a stale cache. While this explains why settings don't appear immediately after an edit, it does not explain why they are missing entirely if the file isn't being read in the first place.

Making .user.ini Work Automatically

To achieve automatic loading without manual flags like php --php-ini .user.ini, you must explicitly enable the feature. This is typically done by setting user_ini.filename to .user.ini. However, this change usually requires editing the main system-wide php.ini or a file in the conf.d directory found via php --ini.

If you are on a shared hosting environment (like cPanel) or using Apache with mod_php, adding display_errors=on to .user.ini often works because the server configuration explicitly enables user_ini.filename = .user.ini. In contrast, a standalone PHP-FPM or CLI installation might disable this by default for security reasons.

If you cannot modify the system-wide php.ini, you can force the behavior programmatically within your script before any output is sent:

<?php
if (ini_get('user_ini.filename') === '' || ini_get('user_ini.filename') === '.htaccess') {
    // Only set this if running in a context where .user.ini is expected
    // Note: This requires the directive to be writable, which varies by environment.
    // ini_set('user_ini.filename', '.user.ini'); 
}

// Ensure you check if the file actually exists before relying on it
$configFile = getcwd() . DIRECTORY_SEPARATOR . '.user.ini';
if (file_exists($configFile)) {
    echo "Found .user.ini in current directory.";
} else {
    echo ".user.ini not found in current directory.";
}
?>

Best Practices for Configuration Management

Relying on .user.ini for critical application logic is generally discouraged. It is a utility file best suited for simple toggles like display_errors, open_basedir (on shared hosting), or specific filter settings. For persistent configuration, environment variables or a dedicated config class are more robust.

If you need to apply these settings globally without modifying system files, consider using Composer's config script or a wrapper script that explicitly loads the ini file before executing your application entry point. This ensures consistency across different environments and avoids the pitfalls of relying on default server configurations that may change silently between hosting providers.

Our network