PHP realpath_cache_size Explained: Configuration, Performance, and Best Practices

Introduction

The realpath_cache_size directive controls the amount of memory PHP allocates for its realpath cache. This cache stores the resolved absolute paths of files and directories, allowing PHP to avoid repeatedly performing filesystem lookups during script execution.

Increasing the cache size can reduce filesystem operations and improve performance, especially for large applications that include many PHP files, such as WordPress, Laravel, Symfony, and other modern frameworks.

This guide explains how realpath_cache_size works, how to configure it, recommended values, and best practices for production environments.

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_size?

Whenever PHP opens a file using functions such as include, require, include_once, or require_once, it must resolve the file's absolute path.

For example:

require 'config/database.php';

PHP converts the relative path into its absolute location before loading the file.

Without caching, this lookup happens every time the script runs.

The realpath_cache_size directive determines how much memory PHP can use to store these resolved paths.

Example:

realpath_cache_size = 4096K

How realpath Cache Works

Without caching:

PHP Request
      │
      ▼
include()
      │
      ▼
Filesystem Lookup
      │
      ▼
Load File

Every request performs filesystem lookups.

With the cache enabled:

PHP Request
      │
      ▼
Realpath Cache
      │
 ┌────┴────┐
 │         │
Hit       Miss
 │         │
 ▼         ▼
Load    Filesystem Lookup
File         │
             ▼
        Store in Cache

When the path is already cached, PHP skips the filesystem lookup and loads the file more efficiently.

Check the Current Value

Run:

php -i | grep realpath_cache_size

Example output:

realpath_cache_size => 4096K => 4096K

Locate the Active php.ini File

php --ini

Example:

Loaded Configuration File: /etc/php.ini

For websites using PHP-FPM, make sure you edit the configuration file used by PHP-FPM.

Change realpath_cache_size

Open the configuration file.

sudo nano /etc/php.ini

Find:

realpath_cache_size = 4096K

Example:

realpath_cache_size = 16384K

Save the file.

Restart PHP-FPM

Apply the changes.

sudo systemctl restart php-fpm

Verify the service:

sudo systemctl status php-fpm

Expected output:

Active: active (running)

Verify the Configuration

Run:

php -i | grep realpath_cache_size

Or use:

<?php
phpinfo();

Search for:

realpath_cache_size

Recommended Values

| Application                   | Recommended Value |
| ----------------------------- | ----------------- |
| Small websites                |                4M |
| WordPress                     |                8M |
| Laravel                       |               16M |
| Symfony                       |               16M |
| Large enterprise applications |           16M–32M |

The optimal value depends on the number of PHP files and directories your application accesses.

realpath_cache_size vs OPcache

These directives improve performance in different ways.

| Directive                    | Purpose                          |
| ---------------------------- | -------------------------------- |
| `realpath_cache_size`        | Caches resolved filesystem paths |
| `opcache.memory_consumption` | Stores compiled PHP bytecode     |

Both features complement each other.

A request typically follows this flow:

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

The realpath cache avoids repeated path resolution, while OPcache avoids recompiling PHP scripts.

Common Issues

Performance Does Not Improve

Possible reasons include:

The application is too small to benefit significantly.

PHP-FPM was not restarted after changing the configuration.

OPcache is disabled.

The filesystem is already very fast, reducing the impact of path caching.

Cache Too Small

Applications with thousands of PHP files may exceed the default cache size.

If the cache fills up, PHP must perform additional filesystem lookups, reducing the performance benefit.

Best Practices

Leave the default value for small applications unless profiling indicates a bottleneck.

Increase the cache size for large frameworks with many PHP files.

Use realpath_cache_size together with OPcache for optimal performance.

Restart PHP-FPM after modifying the configuration.

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

Conclusion

The realpath_cache_size directive controls how much memory PHP allocates for caching resolved filesystem paths. A larger cache can reduce filesystem lookups and improve application performance, particularly for frameworks and content management systems with many included files.

While increasing this value alone will not dramatically speed up every application, it works well alongside OPcache and other PHP performance optimizations to reduce unnecessary overhead and improve overall efficiency.