PHP opcache.save_comments Explained: Configuration, Compatibility, and Best Practices

Introduction

The opcache.save_comments directive determines whether PHP OPcache preserves comments and documentation blocks (DocBlocks) in compiled bytecode. While removing comments can slightly reduce memory usage, many modern PHP frameworks and libraries rely on comments or metadata for reflection, annotations, documentation generation, and other runtime features.

For most applications, keeping comments is the recommended and safest configuration.

This guide explains how opcache.save_comments works, how to configure it, when it can be disabled, and its impact on application compatibility.

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 opcache.save_comments?

PHP source files often contain comments and PHPDoc blocks.

Example:

<?php

/**
 * Returns the current user.
 */
function getUser()
{
    return "Alice";
}

The opcache.save_comments directive determines whether these comments are retained in the compiled bytecode.

Enable comment preservation:

opcache.save_comments = 1

Disable comment preservation:

opcache.save_comments = 0

When disabled, comments are discarded during compilation to reduce memory usage.

How It Works

With comment preservation enabled:

PHP Source
     │
     ▼
Compile
     │
     ▼
Bytecode
     │
     ├── Instructions
     └── Comments

With comment preservation disabled:

PHP Source
     │
     ▼
Compile
     │
     ▼
Bytecode
     │
     └── Instructions Only

The executable code remains the same, but comment metadata is no longer available at runtime.

Check the Current Value

Run:

php -i | grep opcache.save_comments

Example output:

opcache.save_comments => On => On

You can also check through:

<?php
phpinfo();

Search for:

opcache.save_comments

Locate the Active Configuration File

Run:

php --ini

Many Linux distributions load OPcache settings from:

/etc/php.d/10-opcache.ini

Always modify the configuration used by PHP-FPM if you are changing settings for a web application.

Change opcache.save_comments

Open the OPcache configuration file.

sudo nano /etc/php.d/10-opcache.ini

Enable comment preservation:

opcache.save_comments = 1

Disable comment preservation:

opcache.save_comments = 0

Save the file.

Restart PHP-FPM

Apply the configuration 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 opcache.save_comments

Why Do Comments Matter?

Although PHP comments are ignored during normal script execution, they can be accessed through the Reflection API.

For example:

<?php

$reflection = new ReflectionFunction('getUser');
echo $reflection->getDocComment();

If opcache.save_comments is disabled, getDocComment() may return false instead of the expected documentation block.

Compatibility with Modern Frameworks

Many PHP frameworks and tools historically relied on PHPDoc comments.

Examples include:

Doctrine ORM annotations

Swagger/OpenAPI generators

API documentation tools

Reflection-based libraries

Custom annotation parsers

Modern PHP also supports Attributes (introduced in PHP 8), which provide structured metadata without relying on comments. Even so, many existing libraries and applications continue to use PHPDoc for compatibility and documentation.

Does It Affect Performance?

Disabling comment preservation can:

Reduce OPcache memory usage slightly.

Decrease the size of cached bytecode.

However, the performance improvement is usually very small for modern applications.

In contrast, disabling comments may break software that depends on runtime access to PHPDoc information.

For most production servers, compatibility is more valuable than the small memory savings.

Recommended Values

| Environment                      |                             Recommended Value |
| -------------------------------- | --------------------------------------------- |
| Local development                |                                           `1` |
| Testing                          |                                           `1` |
| Production (modern applications) |                                           `1` |
| Specialized embedded systems     | `0` (only if compatibility has been verified) |

For the majority of websites and applications, leaving this option enabled is the safest choice.

Common Issues

Reflection Does Not Return PHPDoc Comments

Possible cause:

opcache.save_comments = 0

Enable comment preservation and restart PHP-FPM.

Framework Features Stop Working

Some frameworks or libraries expect PHPDoc metadata to be available.

If annotations or documentation-based features stop functioning, verify that comments are being preserved.

No Noticeable Performance Improvement

Disabling comments saves only a small amount of memory.

For most applications, tuning opcache.memory_consumption and opcache.max_accelerated_files provides a much greater performance benefit.

Relationship with Other OPcache Settings

opcache.save_comments works alongside other OPcache directives.

PHP Request
      │
      ▼
OPcache
      │
      ├── enable
      ├── memory_consumption
      ├── max_accelerated_files
      ├── validate_timestamps
      ├── revalidate_freq
      └── save_comments
      │
      ▼
Execute Script

Together, these settings determine how OPcache stores, validates, and serves compiled PHP scripts.

Best Practices

Keep opcache.save_comments = 1 for most applications.

Disable it only after confirming that no library or framework depends on PHPDoc comments.

Restart PHP-FPM after changing the setting.

Test applications thoroughly before deploying changes to production.

Focus first on optimizing memory allocation and cache sizing before considering comment removal.

Conclusion

The opcache.save_comments directive controls whether PHP OPcache preserves comments and PHPDoc blocks in cached bytecode. While disabling comment preservation can slightly reduce memory usage, it may also affect reflection, annotation-based libraries, and documentation tools.

For modern PHP applications, the recommended configuration is to keep opcache.save_comments enabled unless you have carefully verified that your application and all of its dependencies do not require runtime access to PHPDoc comments.