PHP realpath_cache_ttl Explained: Configuration, Performance, and Best Practices

Introduction

The realpath_cache_ttl directive controls how long PHP keeps resolved filesystem paths in the realpath cache before they expire. It works together with realpath_cache_size to improve performance by reducing repeated filesystem lookups.

Choosing an appropriate cache lifetime helps balance performance and file change detection. A longer cache lifetime reduces filesystem operations, while a shorter lifetime allows PHP to detect file system changes more quickly.

This guide explains how realpath_cache_ttl works, how to configure it, recommended values for different environments, and common troubleshooting scenarios.

Test Environment

Operating System : AlmaLinux 10
PHP Version      : PHP 8.3
Web Server       : Nginx
PHP-FPM          : Enabled
Architecture     : x86_64
Last Tested      : July 2026

What Is realpath_cache_ttl?

When PHP resolves a file path, it stores the result in the realpath cache.

For example:

require 'config/database.php';

Instead of resolving the same path on every request, PHP can reuse the cached result until it expires.

The realpath_cache_ttl directive specifies how long, in seconds, each cached path remains valid.

Example:

realpath_cache_ttl = 120

In this example, cached paths remain valid for 120 seconds before PHP checks the filesystem again.

How realpath_cache_ttl Works

PHP Request
      │
      ▼
Resolve File Path
      │
      ▼
Store in Realpath Cache
      │
      ▼
TTL Countdown
      │
 ┌────┴────┐
 │         │
Valid    Expired
 │         │
 ▼         ▼
Reuse   Resolve Again
Cache     │
           ▼
      Update Cache

While the cache entry remains valid, PHP reuses it instead of performing another filesystem lookup.

Check the Current Value

Run:

php -i | grep realpath_cache_ttl

Example output:

realpath_cache_ttl => 120 => 120

Locate the Active php.ini File

php --ini

Example:

Loaded Configuration File: /etc/php.ini

If your website uses PHP-FPM, ensure you edit the configuration file used by PHP-FPM.

Change realpath_cache_ttl

Open the PHP configuration file.

sudo nano /etc/php.ini

Find:

realpath_cache_ttl = 120

Example:

realpath_cache_ttl = 600

Save the file.

Restart PHP-FPM

Apply the changes.

sudo systemctl restart php-fpm

Verify:

sudo systemctl status php-fpm

Expected output:

Active: active (running)

Verify the Configuration

Run:

php -i | grep realpath_cache_ttl

Or create a PHP file:

<?php
phpinfo();

Search for:

realpath_cache_ttl

Recommended Values

| Environment               | Recommended Value |
| ------------------------- | ----------------- |
| Development               |    60–120 seconds |
| Small production websites |       300 seconds |
| WordPress                 |   300–600 seconds |
| Laravel                   |       600 seconds |
| Symfony                   |       600 seconds |
| Large production servers  |  600–1800 seconds |

Development environments benefit from shorter values because file changes are detected more quickly. Production servers usually benefit from longer cache lifetimes because application files change less frequently.

realpath_cache_ttl vs realpath_cache_size

These directives work together but control different aspects of the cache.

| Directive             | Purpose                                        |
| --------------------- | ---------------------------------------------- |
| `realpath_cache_size` | Maximum memory allocated for cached paths      |
| `realpath_cache_ttl`  | Lifetime of each cached path before expiration |

Example configuration:

realpath_cache_size = 16384K

realpath_cache_ttl = 600

Increasing the cache size allows PHP to store more resolved paths, while increasing the TTL allows those cached paths to remain valid for a longer period.

realpath Cache and OPcache

A typical request follows this sequence:

PHP Request
      │
      ▼
Realpath Cache
      │
      ▼
OPcache
      │
      ▼
Execute PHP Script

The realpath cache reduces filesystem lookups, while OPcache avoids recompiling PHP scripts. Together they reduce unnecessary overhead and improve request performance.

Common Issues

Changes to PHP Files Are Not Detected Immediately

If the cache lifetime is very long, PHP may continue using cached path information until the TTL expires.

Restarting PHP-FPM or reducing realpath_cache_ttl can help during development.

No Noticeable Performance Improvement

Possible reasons include:

The application is relatively small.

OPcache already eliminates much of the overhead.

The storage device is very fast, making filesystem lookups inexpensive.

Incorrect Cache Lifetime

A very short TTL causes PHP to perform more filesystem lookups.

A very long TTL may delay the detection of moved or renamed files during active development.

Choose a value that matches your deployment workflow.

Best Practices

Use shorter TTL values during development.

Use longer TTL values on stable production servers.

Configure realpath_cache_ttl together with realpath_cache_size.

Restart PHP-FPM after changing the configuration.

Verify the updated value using phpinfo() or php -i.

Conclusion

The realpath_cache_ttl directive determines how long PHP keeps resolved filesystem paths in memory before refreshing them. Together with realpath_cache_size, it helps reduce repeated filesystem lookups and improve application performance.

For production servers where application files change infrequently, a longer cache lifetime generally provides better performance. During development, shorter values make file changes visible more quickly and simplify testing.