[RFC] [Discussion] OPcache Static Cache

2026年5月17日(日) 5:14 Larry Garfield larry@garfieldtech.com:

Hi internals,

I'd like to start the discussion for a new RFC, OPcache Static Cache.

RFC: https://wiki.php.net/rfc/opcache_static_cache
Implementation: https://github.com/php/php-src/pull/22052

The proposal adds an OPcache-managed shared-memory cache for explicit
userland values and for selected PHP static state. It introduces
explicit functions under the OPcache namespace (volatile_* and
persistent_*) and two attributes, #[OPcache\VolatileStatic] and
#[OPcache\PersistentStatic], that let selected static properties and
method static variables survive across requests. The feature is
disabled by default and only activates once memory is allocated through
the new INI directives.

The RFC covers the motivation, the deliberate split between the two
backends, the trust model (one PHP runtime = one trust domain; this is
not a tenant isolation boundary), and benchmarks against APCu on NTS
php-fpm and ZTS FrankenPHP. The PR is the full implementation, with
PHPT coverage summarized in the Validation section.

One thing to flag on the implementation status: the Windows build is
currently broken. I don't have a Windows development environment
available yet — one is being arranged through work, and I'll get the
Windows side fixed once that's in place.

Feedback welcome.

Best Regards,
Go Kudo

Interesting! I can definitely see uses for it, and I appreciate the level
of detail in the RFC.

Some thoughts, though:

• atomic-decrement throwing if a value doesn't exist sounds like a
  footgun. For something like an up/down voting widget, I could very easily
  see someone hitting the Down Vote button first, which would cause it to
  crash. Having to always check _exists() on decrement but not on increment
  is inconsistent and likely to confuse people.

• Are either of these stores purged on reboot?

• "persistent cache and returns void on success." - No, returns null. You
  can't return void. A function can have a void return type, whether it's
  successful or not. Not quite the same thing.

• Having the locks automatically self-unlock sure sounds elegant at first,
  but the lack of symmetry in the API feels very error prone. People will
  want to use it like a transaction, but since it unlocks on the first write
  there's no way to make it one. It just silently unlocks if certain
  functions are called. But if they're not called, there's no way to unlock
  it. That's even more of an issue in a persistent-process use case, where
  you could easily not hit the process-end for minutes or hours, so the lock
  never automatically clears.

Use case: You need to update some lookup table, so you lock the stored
key, compute the new table, then write the new table. But if the compute
step fails for some reason, you now have a locked value with no way to
unlock it, but no new value to write to it. It's better in many cases to
leave the stale data there rather than delete it, but this API doesn't
offer a way to do that.

• It's not made clear: Do objects have their __serialize() methods called
  when storing (and vice versa on load), or no? "They have to be
  serializable" is not something that can be otherwise determined.

• Status API: Uh, what are the keys? No arrays here please. Please make
  it an object with defined readonly properties. Please.

• You realize you're effectively adding a Memoize attribute to PHP by
  another name, right? Just making sure. :-)

• A property using the volatile-tracking strategy, if run in a persistent
  process, seems like it would never get written. That feels like a problem.

• The section on write times is rather abstract and academic, so a bit
  hard to follow. If I read correctly, though, it means that writing to a
  sub-property of an array/object on a cached property won't trigger a
  resave? That feels like another footgun waiting to happen.

• It's not clear if there's a way to clear an attribute-cached value other
  than nuking the entire volatile/persistent cache. Is there not? It feels
  like there should be one... Especially for "persistent," I don't want to
  have to nuke my entire "persistent" cache from orbit because one value got
  corrupted somehow.

• Defaulting off... I can see the argument for that, but that means it
  will be off for most users. That means I, as a library author of, say, a
  routing system or a DI container, cannot use it, because I have to assume
  most users won't have it. That kneecaps the usefulness of this feature
  dramatically. I would strongly recommend setting at least some default-on
  amount, even if it's only the minimum 8 MB, if we want this feature to
  actually be used. (And I can already think of a few places where I'd want
  to use it myself.)

• Related, what happens if they're disabled but someone tries to use this
  functionality? Does it operate like every read is a cache miss, or does it
  error? If the latter, that means any code that uses the attributes
  REQUIRES that the ini directives be turned on. We generally try to avoid
  this kind of "your code may or may not work depending on ini settings"
  issues. (Hello, magic_quotes!)

• What's the development experience with this? Frequently, in dev mode
  frameworks will disable caches. If the volatile cache just misses silently
  that would work there, but not for the persistent cache. How would I have
  a persistent route cache that is automatically rebuilt on every request
  during development while I'm messing with routes?

• I understand the value of keeping it simple by making it single-tenant.
  However, I can very easily see different 3rd party libraries wanting to
  make use of the cache at the same time. That poses a risk of key-space
  collision, though that's resolvable by a convention to use a key prefix.
  What it does not resolve is cases where one library wants to
  wipe-and-rebuild a dynamic list of keys, but some other library isn't
  expecting a total purge. There's a high risk of libraries stepping on each
  other here.

• Currently, this is just a basic key/value store. That's great for many
  things, but not very queryable. This is absolutely scope creep, but would
  there be some way to extend this (in a future RFC, I'm sure) to allow, say,
  a persistent memory-resident SQLite database? Currently you can write one
  to disk, but then you have to deal with disk permissions. A memory
  resident database now is request-specific, so not useful outside of
  testing. It would be lovely if there were some way to extend in that
  direction.

--Larry Garfield

Hi Larry,

Thank you for the detailed feedback.

I updated the RFC and the implementation to address the concrete API and
documentation issues you pointed out.

https://wiki.php.net/rfc/opcache_static_cache

The main changes are:

• persistent_atomic_decrement() now creates a missing key with -$step,
  matching persistent_atomic_increment().
• volatile_lock() and persistent_lock() now have matching *_unlock()
  functions.
• The lock APIs also accept an optional lease value, so abandoned builder
  reservations can expire even in persistent-worker environments.
• The status APIs now return a read-only OPcache\StaticCacheInfo object
  instead of arrays.
• The RFC now documents that both static-cache backends are scoped to the
  lifetime of the current OPcache static-cache shared-memory segment, and
  are
  not durable storage.
• The wording around persistent_store() was corrected to describe the void
  return type rather than "returning void".
• The RFC now describes when __serialize() and __unserialize() are
  called, and
  that userland serialization keeps those object graphs off the fastest
  direct/shared-graph path.
• The publication rules for VolatileStatic immediate mode, VolatileStatic tracking mode, and PersistentStatic have been expanded.
• VolatileStatic tracking is now documented as publishing at PHP request
  shutdown, not process shutdown, even under FPM/FrankenPHP/persistent
  workers.
• Attribute-backed entries can now be deleted either by loaded class name
  or by
  documented exact static-property/method-static keys, without clearing the
  whole backend.
• I also reran the benchmark matrix from clean NTS FPM, NTS/ZTS CLI, and ZTS
  FrankenPHP builds, and updated the RFC tables.

Some of the broader points are open questions or design tradeoffs rather
than
direct fixes.

On the default-off setting, I want to be more direct about where I actually
stand. I would prefer this feature to be default-on. Administrator opt-in
noticeably limits library adoption, and that significantly reduces the value
of the API as a portable primitive that libraries can rely on being present.

What is holding me back is the shared-hosting case. The cache is a single
shared-memory trust domain, so on a host where multiple tenants share one
OPcache segment, default-on without an isolation story could expose those
tenants to each other through the static cache. I do not yet have a design I
am confident makes default-on safe in that environment, and that is the only
reason the RFC currently ships with the feature disabled.

I would genuinely appreciate your input here. If you (or anyone on the list)
see a viable path — per-pool / per-SAPI segments, a trust-domain or
namespace
mechanism enforced by the engine, a configuration model where the host opts
in per vhost rather than per server, or something I have not considered — I
would be very happy to rework the proposal around it. If we can land on a
model that is safe for shared hosting, I would gladly flip the default in
this RFC rather than defer it to a follow-up.

For disabled backends, the explicit APIs fail rather than silently
pretending
to be a miss-only cache. Attribute-backed state falls back to ordinary
request
local static behavior when the corresponding backend is unavailable. I can
add
a short FAQ entry for this development-mode behavior if that would make the
RFC
clearer.

For multi-library key collisions, the explicit cache remains a shared
namespace
and applications/libraries still need key prefixes, similar to APCu. The new
attribute deletion and exact-key deletion support should reduce the need for
whole-backend clears, but this RFC does not add a separate namespace
mechanism.
I left the broader trust-domain/namespace question as an Open Issue, and it
is
closely related to the shared-hosting question above.

The memory-resident SQLite idea is interesting, but I think it is outside
the
scope of this RFC. This proposal is intentionally a small key/value and
static
state facility first.

Thanks again. The feedback helped make several parts of the API much more
explicit.

Best Regards,
Go Kudo

Hi,

2026年5月17日(日) 0:19 Go Kudo zeriyoshi@gmail.com:

Hi internals,

I'd like to start the discussion for a new RFC, OPcache Static Cache.

RFC: https://wiki.php.net/rfc/opcache_static_cache
Implementation: https://github.com/php/php-src/pull/22052

The FPM shared hosting part is a problem and I don't think this can be
default and probably cannot even be optional. The reason is that we
consider data leaks between pools as security issues so I don't think we
can have some feature that is actually causing a security issue. It will be
a bit tricky to decide what to do if this passes in the current form
because we would probably need to apply security fix and disable it. If you
really want to have it enabled, we would need to explicitly state in the
policy and docs that pool boundary is no longer considered as a security
boundary which would be quite problematic for some shared hosting that rely
on it. Maybe the solution would be to allow it only if there is one pool
enabled.

Kind regards,

Jakub

2026年5月17日(日) 0:19 Go Kudo zeriyoshi@gmail.com:

Hi internals,

I'd like to start the discussion for a new RFC, OPcache Static Cache.

RFC: https://wiki.php.net/rfc/opcache_static_cache
Implementation: https://github.com/php/php-src/pull/22052

The proposal adds an OPcache-managed shared-memory cache for explicit userland values and for selected PHP static state. It introduces explicit functions under the OPcache namespace (volatile_* and persistent_*) and two attributes, #[OPcache\VolatileStatic] and #[OPcache\PersistentStatic], that let selected static properties and method static variables survive across requests. The feature is disabled by default and only activates once memory is allocated through the new INI directives.

The RFC covers the motivation, the deliberate split between the two backends, the trust model (one PHP runtime = one trust domain; this is not a tenant isolation boundary), and benchmarks against APCu on NTS php-fpm and ZTS FrankenPHP. The PR is the full implementation, with PHPT coverage summarized in the Validation section.

One thing to flag on the implementation status: the Windows build is currently broken. I don't have a Windows development environment available yet — one is being arranged through work, and I'll get the Windows side fixed once that's in place.

Feedback welcome.

Best Regards,
Go Kudo

Hi Nicolas, Jakub, Timo, Larry

I update RFC and Implementation:
RFC: https://wiki.php.net/rfc/opcache_static_cache
PR: https://github.com/php/php-src/pull/22052

I'm only responding to bits here and there, because the LLM text here is just too much for me to bother reading. (Frankly, your non-LLM follow up message was perfectly readable to me. I don't think you need it.)

It also seems like you're rewriting the RFC every time someone posts a comment. There are differences of opinion on the list, so it will be less work for you and everyone else to slow down and let more people comment before you start making radical changes.

The resulting public API

For reference, here is the shape the explicit API settled into, summarised
from the stub:

namespace OPcache;

// Explicit cache: two final classes, static methods only, no instances.
final class VolatileCache
{
    public static function get(string $key, 
null|bool|int|float|string|array|object $default = null): 
null|bool|int|float|string|array|object;
    public static function getMultiple(array $keys, ?array $default = 
null): array|false;
    public static function set(string $key, 
null|bool|int|float|string|array|object $value, int $ttl = 0): bool;
    public static function setMultiple(array $values, int $ttl = 0): 
bool;
    public static function has(string $key): bool;
    public static function delete(string $key_or_class): bool;
    public static function deleteMultiple(array $keys): bool;
    public static function clear(): bool;
    public static function lock(string $key, int $lease = 0): bool;
    public static function unlock(string $key): bool;
    public static function getCacheStoreType(string $key_or_property, 
?string $class_name = null): CacheStoreType;
    public static function `info()`: StaticCacheInfo;
}

// PinnedCache is the same set, except set()/setMultiple() take no $ttl,
// plus two atomic counters:
final class PinnedCache
{
    // get/getMultiple/set/setMultiple/has/delete/deleteMultiple/clear/
    // lock/unlock/getCacheStoreType/info  -- as above
    public static function increment(string $key, int $step = 1): int|false;
    public static function decrement(string $key, int $step = 1): int|false;

No int|false. That's an anti-pattern. If you must do "int or error", at the very least use null here.

}

// getCacheStoreType() reports how a value is stored, without decoding it:
enum CacheStoreType
{
case NotFound; // no entry for the key/property
case Scalar; // stored inline
case SharedGraph; // zero-copy graph laid out in SHM (the fast path)
case OPcacheSerialized; // OPcache binary serializer (SHM-safe, no userland)
case PHPSerialized; // php_var_serialize() last resort
}

// Declarative static state, over the same storage:
#[Attribute] final class VolatileStatic {
public function __construct(int $ttl = 0, CacheStrategy $strategy =
CacheStrategy::Immediate);
}
#[Attribute] final class PinnedStatic {}
enum CacheStrategy: int { case Immediate = 0; case Tracking = 1; }

// Status object and the single exception type:
final readonly class StaticCacheInfo { /* enabled, available,
configured_memory, entry_count, ... */ }
class StaticCacheException extends \Exception {}

Two final classes with static methods, no instances and no shared
interface. Misses and contention return the default or `false`; genuine
backend failures return `false` (or `int|false` for the atomic counters);
`Closure` and resource values are rejected with a `TypeError`; and
`StaticCacheException` is reserved for strict `#[OPcache\PinnedStatic]`
publication.

I want to be clear on this: I will absolutely vote against this proposal if it ships with static methods as the API, no matter what else it contains. That is a horrible anti-pattern and it should not be brought anywhere close to PHP's stdlib. No. Absolutely not.

Nicolas' original proposal was for regular objects, with a factory method. I also prefer a regular object, but I'd go a step further:

$volatile = new VolatileCache('some_key');
$volatile->set('key', $val);

Pass a "scoping key" (or namespace, or prefix, or whatever you want to call it) to the constructor of the cache objects. In most cases, frameworks (like Symfony or Laravel) already have an app-key value that is unique to the app instance, and that can be used probably directly. That provides a clear separation between different cache pools; even if you have a multi-tenant setup such as apache2, using different random strings for the scoping key will keep the values separate.

That gives us a clear separation, and justification for shipping on-by-default.

(This is what I meant earlier when talking about "pools." That's essentially what this is.)

Also: I really don't like the name "pinned." The opposite of "Volatile" is usually "stable". That's less misleading than "persistent" (the original name), but also less confusing than "pinned", which means nothing here.

References and the silent fallback

I honestly didn't follow this section. Probably because of the LLM.

Scalars and arrays-of-scalars only

This is where the discussion helped most. I argued before that scalars-only
gave up a real win; you pushed back with measurements; so I built your setup
and measured it properly, including the large nested workloads that are the
actual case for a cache. You were right that native was losing. That sent me
into the implementation, and I found the cause and fixed it. The path is
worth setting out.

Two of your framings I agree with up front:

1. For array-of-scalars config/metadata, an immutable interned array is
   essentially free, and the cache should not claim to beat it.
2. The "Nx faster than APCu" headline is size-dependent; APCu is only a few
   microseconds for small payloads.

I can see Nicolas' argument for scalar/arrays-only, but I also agree that does greatly limit its usefulness. You would need to spend a great deal of effort building an object facade for that data in many cases. That's going to eat up a large chunk of the benefit (in both dev time and run time) of this feature.

Put another way, if I can just build up a data structure on a property, stick an attribute on it, and then always use it like:

$data = self::$data ??= compute_data();

And move on with life, that's huge for DX, even if it may be slightly slower than taking the time to compile an array form of it, save it to disk (and worry about file permissions and writeability), reload it, and then rehydrate to objects, potentially. Frankly, I'd take that tradeoff more often than not.

(d) Not just performance

This does not rest on performance alone. Object support is also useful for
being built in and generic (no third-party extension, nothing to pre-generate)
and for being one primitive: the store side and the runtime cross-worker
sharing live in the same place, instead of "cache the array" plus "hydrate in
userland" wired together by every library. And the safe-direct registry is not
a userland protocol: a plain user object with no magic and no cycles or refs
takes the fast path automatically via can_restore_direct(), and the C-only
registry only covers a few internal classes whose state the generic path
cannot read. Keeping objects imposes nothing on the ecosystem.

Right, that. The simplicity of the userland code is the big win for me, even if it's single-digit-percent slower than manually materializing in some cases.

Dropping pinned (and the attributes)

PinnedStatic on the Carbon shape is ~1.5 us [...] there's no preload
trick that reaches that number, because preload can't bake a live object
graph into an opcode literal

Pinned is the one place a live-object representation still wins clearly, for a
reason the volatile numbers above do not capture. Pinned (and
#[PinnedStatic]) materialize the graph once per worker; after that it is a
plain static read on every subsequent request in that worker, near zero per
request. The hydration approach pays its hydrate cost on every request instead.
preload cannot reach this either: it can only intern scalar and array
literals, not bake a live object graph into an opcode literal.

The caveat is that this holds for read-only / immutable shared state, where
keeping one live instance across requests is correct; a mutable shared instance
would leak between requests. But that is a real and common case: a compiled DI
container, a routing table, config value objects. Your request-registry counter
rebuilds per request from the cache, so it does not reach the per-worker
amortization, and for the read-only data where it would help, pinned already
does it with less per-request cost.

The attributes are the ergonomic surface over that same mechanism, so I would
keep them in this RFC rather than split them out. They add no new storage
model; they remove the explicit store/fetch boilerplate for the static-state
case.

I would prefer to keep these in rather than remove them, but I wouldn't vote against the RFC if the consensus is eventually to remove them until later.

--Larry Garfield

Le mar. 2 juin 2026 à 15:12, Go Kudo zeriyoshi@gmail.com a écrit :

2026年5月17日(日) 0:19 Go Kudo zeriyoshi@gmail.com:

Hi internals,

I'd like to start the discussion for a new RFC, OPcache Static Cache.

RFC: https://wiki.php.net/rfc/opcache_static_cache
Implementation: https://github.com/php/php-src/pull/22052

The proposal adds an OPcache-managed shared-memory cache for explicit
userland values and for selected PHP static state. It introduces explicit
functions under the OPcache namespace (volatile_* and persistent_*) and two
attributes, #[OPcache\VolatileStatic] and #[OPcache\PersistentStatic], that
let selected static properties and method static variables survive across
requests. The feature is disabled by default and only activates once memory
is allocated through the new INI directives.

The RFC covers the motivation, the deliberate split between the two
backends, the trust model (one PHP runtime = one trust domain; this is not
a tenant isolation boundary), and benchmarks against APCu on NTS php-fpm
and ZTS FrankenPHP. The PR is the full implementation, with PHPT coverage
summarized in the Validation section.

One thing to flag on the implementation status: the Windows build is
currently broken. I don't have a Windows development environment available
yet — one is being arranged through work, and I'll get the Windows side
fixed once that's in place.

Feedback welcome.

Best Regards,
Go Kudo

Hi Nicolas, Jakub, Timo, Larry

I update RFC and Implementation:
RFC: https://wiki.php.net/rfc/opcache_static_cache
PR: https://github.com/php/php-src/pull/22052

I'm folding replies to all three of you into one message, since the
threads overlap. Most of it answers Nicolas's measurements; further down
there is a section for Jakub's FPM pool-isolation concern and a short note
for Timo's pointer to prior art.

Nicolas, thank you for building my branch and running your own A/B/C
measurements. That moved the discussion onto concrete ground, and I
appreciate it.

Since your review I have pushed a revised branch and bumped the RFC to
2.0.0. The API changes discussed below are in it (the SAPI opt-in model,
and getCacheStoreType() for storage-path visibility), and the object
workloads you flagged are now substantially faster: native now beats the
deepclone path on every nested case I tried. Details and numbers follow.

I agree with most of your points. I'll go through them in order, concede
the ones where you are right, and try to narrow what is left. I think it
comes down to one question: whether a userland array-hydration layer is an
acceptable replacement for engine-level object storage. Most of the rest I
can give you.

The resulting public API

For reference, here is the shape the explicit API settled into, summarised
from the stub:

namespace OPcache;

// Explicit cache: two final classes, static methods only, no instances.
final class VolatileCache
{
    public static function get(string $key,
null|bool|int|float|string|array|object $default = null):
null|bool|int|float|string|array|object;
    public static function getMultiple(array $keys, ?array $default =
null): array|false;
    public static function set(string $key,
null|bool|int|float|string|array|object $value, int $ttl = 0): bool;
    public static function setMultiple(array $values, int $ttl = 0): bool;
    public static function has(string $key): bool;
    public static function delete(string $key_or_class): bool;
    public static function deleteMultiple(array $keys): bool;
    public static function clear(): bool;
    public static function lock(string $key, int $lease = 0): bool;
    public static function unlock(string $key): bool;
    public static function getCacheStoreType(string $key_or_property,
?string $class_name = null): CacheStoreType;
    public static function `info()`: StaticCacheInfo;
}

// PinnedCache is the same set, except set()/setMultiple() take no $ttl,
// plus two atomic counters:
final class PinnedCache
{
    // get/getMultiple/set/setMultiple/has/delete/deleteMultiple/clear/
    // lock/unlock/getCacheStoreType/info  -- as above
    public static function increment(string $key, int $step = 1):
int|false;
    public static function decrement(string $key, int $step = 1):
int|false;
}

// getCacheStoreType() reports how a value is stored, without decoding it:
enum CacheStoreType
{
    case NotFound;          // no entry for the key/property
    case Scalar;            // stored inline
    case SharedGraph;       // zero-copy graph laid out in SHM (the fast
path)
    case OPcacheSerialized; // OPcache binary serializer (SHM-safe, no
userland)
    case PHPSerialized;     // php_var_serialize() last resort
}

// Declarative static state, over the same storage:
#[Attribute] final class VolatileStatic {
    public function __construct(int $ttl = 0, CacheStrategy $strategy =
CacheStrategy::Immediate);
}
#[Attribute] final class PinnedStatic {}
enum CacheStrategy: int { case Immediate = 0; case Tracking = 1; }

// Status object and the single exception type:
final readonly class StaticCacheInfo { /* enabled, available,
configured_memory, entry_count, ... */ }
class StaticCacheException extends \Exception {}

Two final classes with static methods, no instances and no shared
interface. Misses and contention return the default or false; genuine
backend failures return false (or int|false for the atomic counters);
Closure and resource values are rejected with a TypeError; and
StaticCacheException is reserved for strict #[OPcache\PinnedStatic]
publication.

SAPI availability: the unsafe flag is gone, opt-in instead

these are safe SAPIs, they just don't have a scoping concept built in
[...] enable it by default with a single default scope for those SAPIs,
plus a clear internal API so a SAPI can define its own scoped segments

I implemented it the way you suggested. There is no longer an
opcache.static_cache.allow_unsafe_runtime directive and no SAPI-name
allowlist in the engine. Availability is opt-in: a SAPI, or an embedder,
calls a small internal C API, zend_opcache_static_cache_opt_in(), before
request handling to enable Static Cache for its runtime. That call is the
runtime declaring that a trust/storage boundary holds for the lifetime of
the shared-memory owner.

The bundled fpm, cli, cli-server and phpdbg SAPIs call it at
startup, so they are available by default. The difference from before is
the
mechanism: instead of the engine guessing from the SAPI name and offering
an
"unsafe" override, each runtime states that it owns a boundary. A runtime
with a real per-tenant boundary scopes it with the partition API
(zend_opcache_static_cache_partition_create / _activate, which fpm
already uses per pool). A runtime without one, such as a shared
multi-tenant
web SAPI with no pre-request identity, never opts in and stays unavailable,
with nothing left to misconfigure.

The embed SAPI does not auto-opt-in, on purpose. The embedding
application
owns the runtime and its trust boundary, so it opts in from its own startup
code. That keeps the rule consistent for every embedder, including one that
registers its own SAPI module instead of reusing the bundled embed one.
FrankenPHP does exactly that, so it opts in with the same one-line call
(or a
scoped partition when it isolates per worker); there is no embed
special-case that covers php_embed users but silently misses FrankenPHP.

That is your internal-API point, and it removes the naming question by
deleting the flag entirely. The full ext/opcache suite passes with the
directive gone.

API shape: remember()

I could also add VolatileCache::remember($key, $compute, $ttl = 0)
wrapping the safe lock -> build-outside-the-lock -> store sequence

I would rather not add this one. remember() takes a callable, and to
actually prevent a stampede it has to hold the entry lock across the call
to
$compute(). That means running arbitrary userland PHP while holding a
cross-process SHM lock. The callable can run unbounded, throw, fork, or
re-enter the cache, and a re-entrant lock() on the same key (or a key in
the same lock stripe) while the lock is held is a deadlock. The lease
bounds
the duration, but not the re-entrancy and not the exception path.

Not holding the lock while computing gives no stampede protection at all;
it
is then just sugar over get()-then-set() that looks atomic, which is
worse than not having it.

Since I already expose lock()/unlock() with a lease, userland can do
the
safe thing itself, with the compute step outside any engine lock:

if (!VolatileCache::lock($key, $lease)) {
    return VolatileCache::get($key, $default);
}
try {
    $value = $compute(); // runs outside the engine lock
    VolatileCache::set($key, $value, $ttl);
    return $value;
} finally {
    VolatileCache::unlock($key);
}

That keeps the closure's execution, its scope, and any exception it throws
in
userland, never inside the engine's critical section. I would rather
document
this recipe than move userland execution into the primitive. If you see a
safe construction I have missed, I will reconsider.

References and the silent fallback

I'd rather make it visible (surface the chosen path in info(), or in a
debug build) than ban objects

Agreed, and that is implemented: visibility, not a ban. There is a new
introspection method on both cache classes:

VolatileCache::getCacheStoreType(string $key_or_property, ?string
$class_name = null): OPcache\CacheStoreType
PinnedCache::getCacheStoreType(string $key_or_property, ?string
$class_name = null): OPcache\CacheStoreType

It returns an OPcache\CacheStoreType enum (NotFound, Scalar,
SharedGraph, OPcacheSerialized, PHPSerialized), so you can see per
key
which path a value took, without decoding it, in any build rather than
only a
debug one. Passing $class_name inspects the attribute-backed
static-property storage for that class instead of an explicit key. A value
that fell back to serialization is now one call away from being observable.

The enum also pins down a correction. The first fallback off the shared
graph
is not php_var_serialize but the OPcache binary serializer, which is
SHM-safe and runs no userland code. That is why getCacheStoreType reports
OPcacheSerialized and PHPSerialized as separate cases;
php_var_serialize
is the last resort, not the first. So "bail == APCu parity" understates the
middle tier, though your underlying point holds: even that tier is slower
than
the fast path and should be visible.

no real objection to rejecting top-level hard refs up front [...]
"top-level hard ref" confuses me

You are right to be confused, and I will retract the phrase; it is a no-op.
store($key, $value) takes $value by value, so the engine dereferences
any
top-level reference (ZVAL_DEREF) before storage ever sees it. A top-level
hard ref cannot reach the storage layer as a reference. The case that
matters
is a nested reference, a & inside an array element or object property,
and
that cannot be rejected cheaply up front: detecting it requires walking the
whole graph, which is the walk the shared-graph builder already does. So
the
honest answer for nested refs is the visibility above (the value reports
the
serialize path), not an up-front rejection.

Scalars and arrays-of-scalars only

This is where the discussion helped most. I argued before that scalars-only
gave up a real win; you pushed back with measurements; so I built your
setup
and measured it properly, including the large nested workloads that are the
actual case for a cache. You were right that native was losing. That sent
me
into the implementation, and I found the cause and fixed it. The path is
worth setting out.

Two of your framings I agree with up front:

1. For array-of-scalars config/metadata, an immutable interned array is
   essentially free, and the cache should not claim to beat it.
2. The "Nx faster than APCu" headline is size-dependent; APCu is only a few
   microseconds for small payloads.

(a) The config array

an immutable array is essentially free (0.045 us) [...] the static
cache's own array fetch, which pays an O(n) walk per read and so doesn't
even deliver the immutable-array win that opcache literals already give

You are structurally right, and I have fixed it. Two facts first. I could
not
reproduce 331 us: a pure-scalar 4k-entry array fetches in about 7 us,
scaling
at roughly 1.7 ns/entry, and the decode itself was already zero-copy (a
scalar array is stored once as IS_ARRAY_IMMUTABLE and returned as
ZVAL_ARR() straight into SHM). The O(n) you felt was one layer up: every
warm fetch re-walked the array in value_needs_request_local_clone() to
decide whether it needed a deep clone, when that answer is fixed at store
time. I removed that walk for shared-graph values (the same change as in
(c)); the 4k fetch is now about 0.64 us and flat in the entry count.

It is still not the 0.014 us of a resident literal read, and I am not
claiming it should be. For read-only scalar config the preload/literal path
wins, and that is fine. It is a separate matter from objects.

(b) Objects: I measured your A/B/C, found native losing, and chased why

I built this branch with APCu master and your deepclone, all NTS, JIT off,
timing warm fetches where C rebuilds the same isolated object graph B
returns
(resident dehydrated array plus deepclone_from_array). As you said,
native
lost, and worse as the graph grew. us/op:

array of nested ORM entities     objects   A apcu   B native   C hydrate
                                     1000     1800        799        501
                                     2000     4171       1903       1043
object tree                          8191     1582       1736        498
                                     9841     1928       1836        523

Two things you were right about that I had wrong: deepclone_to_array /
deepclone_from_array are generic (no per-class hydrator to charge for),
and
C hands back the same isolated objects B does. So this was a real loss,
not a
measurement artifact.

The cause was structural, but not where I first guessed. The warm fetch
kept
a request-local prototype of the materialized graph and deep-cloned it on
every repeat fetch, and for an object graph that clone is slower than
decoding
the compact SHM layout again. A shared graph never holds shared identity or
cycles, so each decode is already an independent copy; the prototype was
pure
overhead. On top of that the decoder re-resolved the class
(zend_lookup_class) for every object, and the builder stored a separate
copy
of each repeated class and property name.

(c) The fix

Three changes, all behind the existing API, with no visible behaviour or
format change:

• Skip the request-local prototype for shared-graph values and decode from
  SHM on each fetch. (This also removes the O(n) array walk in (a).)
• Deduplicate equal strings within a payload at build time, so a class or
  property name repeated across thousands of objects is stored once.
• Memoize the resolved class per (buffer, offset) during a decode, so a
  homogeneous graph resolves its class once, not once per node.

Same A/B/C after the change, NTS, JIT off, us/op:

array of nested ORM entities     objects   A apcu   B native   C hydrate
                                     1000     1781        357        492
                                     2000     3868        721       1036
object tree                          8191     1565        462        485
                                     9841     1830        499        513

Native now beats deepclone on every nested workload I tried: about 1.4x on
the 2000-entity array, and the deep trees that lost 3.5x now win. The
400-object case went from 72 to 23 us. The full ext/opcache suite passes,
plus new regression tests, on NTS and ZTS.

To make this reproducible on your terms, I added a deepclone backend to my
own
HTTP benchmark harness (dehydrate with deepclone_to_array(), keep the
array
in the volatile cache, rehydrate with deepclone_from_array() on each
fetch)
and re-ran vote_read_long under the published conditions (php-fpm + nginx
NTS and FrankenPHP ZTS, 20 iterations / 3 warmup / 3000 ops, JIT off). The
APCu baselines match the published table within about 2%, so the runtimes
are
comparable. native vs deepclone, mean us/op (NTS):

workload                 APCu     native   deepclone
route_table_read        161.2      0.90      0.91     (array: tie)
large_array              90.9      0.88      0.88     (array: tie)
metadata_object_read    185.3      1.12      1.32     (native)
metadata_object_mutate  162.4      1.03      1.19     (native)
safe_direct_object        2.5      1.22      3.03     (native; deepclone
slower than APCu)
carbon_datetime_object  185.4     46.0     166.3      (native, ~3.6x)
spl_collection_object    21.0      5.48      1.89     (deepclone)

So under the RFC's own methodology native is faster than the deepclone
path on
every object workload except SPL collections, and ties on arrays. The SPL
case
is the one real win for deepclone, and it is specific: those classes go
through
the safe-direct serialized path, whose per-fetch copy handler is heavier
than
rebuilding from a flat array. I have noted it in the RFC as a concrete
follow-up (a tighter SPL copy handler); it does not change the overall
picture.
The updated tables are in the RFC.

Honest edges remain: for a tiny object deepclone's tight path is a hair
faster
(sub-microsecond), and for read-only scalar config a resident literal still
wins outright, as in (a). But for the workload this feature is actually
for,
large nested object graphs from a database, in-engine storage is now the
faster option.

(d) Not just performance

This does not rest on performance alone. Object support is also useful for
being built in and generic (no third-party extension, nothing to
pre-generate)
and for being one primitive: the store side and the runtime cross-worker
sharing live in the same place, instead of "cache the array" plus "hydrate
in
userland" wired together by every library. And the safe-direct registry is
not
a userland protocol: a plain user object with no magic and no cycles or
refs
takes the fast path automatically via can_restore_direct(), and the
C-only
registry only covers a few internal classes whose state the generic path
cannot read. Keeping objects imposes nothing on the ecosystem.

Dropping pinned (and the attributes)

PinnedStatic on the Carbon shape is ~1.5 us [...] there's no preload
trick that reaches that number, because preload can't bake a live object
graph into an opcode literal

Pinned is the one place a live-object representation still wins clearly,
for a
reason the volatile numbers above do not capture. Pinned (and
#[PinnedStatic]) materialize the graph once per worker; after that it is
a
plain static read on every subsequent request in that worker, near zero per
request. The hydration approach pays its hydrate cost on every request
instead.
preload cannot reach this either: it can only intern scalar and array
literals, not bake a live object graph into an opcode literal.

The caveat is that this holds for read-only / immutable shared state, where
keeping one live instance across requests is correct; a mutable shared
instance
would leak between requests. But that is a real and common case: a
compiled DI
container, a routing table, config value objects. Your request-registry
counter
rebuilds per request from the cache, so it does not reach the per-worker
amortization, and for the read-only data where it would help, pinned
already
does it with less per-request cost.

The attributes are the ergonomic surface over that same mechanism, so I
would
keep them in this RFC rather than split them out. They add no new storage
model; they remove the explicit store/fetch boilerplate for the
static-state
case.

Where this leaves us

What is already done or committed: the SAPI opt-in model (the
allow_unsafe_runtime flag and the SAPI allowlist are gone, replaced by
the
internal opt-in/partition API); the error model; storage-path visibility
via
getCacheStoreType(); dropping the "top-level ref" idea; the config-array
fix
(skipping the request-local prototype for shared graphs, which removes the
per-fetch array walk so a warm scalar-array fetch is zero-copy); and the
large-nested object path from (d), with numbers on this same A/B/C. I am
declining remember(), for the lock-safety reason above.

On the central question I went where the measurements led. You were right
that
native lost as shipped; I found why (a request-local prototype clone slower
than re-decoding, plus per-object class lookups and duplicated strings),
fixed
all three, and native now beats your deepclone path on the nested object
workloads, with the full opcache suite and new regression tests passing on
NTS
and ZTS. For tiny objects deepclone is still a hair ahead, and for
read-only
scalar config a resident literal still wins; I concede both.

So I do think in-engine object storage earns its place now, on performance
and
on being a built-in, generic, single primitive (and on pinned's per-worker
amortization for read-only state). But if the body still prefers a focused
better-APCu plus a core hydration primitive, that is an outcome I can
support;
the capability matters to me more than where it sits, and the work above
transfers either way.

The revised branch is pushed and the harness is published, so you can check
the numbers directly; I will also post the full before/after A/B/C here.
If you
have a methodology you would prefer, I will run that too.

Thanks again. This got much sharper because you measured it, and it sent
me to
a fix I would not have found otherwise.

Jakub: the FPM pool boundary is preserved

The FPM shared hosting part is a problem [...] we consider data leaks
between pools as security issues [...] Maybe the solution would be to
allow it only if there is one pool enabled.

This is the concern I most wanted to get right, and I think the
implementation
answers it without the single-pool restriction. Static Cache is not one
cache
shared across pools. FPM creates a separate partition per worker pool in
the
master, before any worker forks; each partition owns its own volatile and
pinned shared-memory backend, and each worker activates only its own pool's
partition during child initialization, before user code runs. Every cache
API,
status call, clear, and the Static Cache part of opcache_reset()
operates on
the active pool's partition. There is no API path from one pool to another
pool's data, so the pool boundary stays a security boundary and no policy
change is needed. If a pool's partition fails to start it gets no Static
Cache;
it never falls back to a shared one.

One honest caveat, for the record: the per-pool segments are anonymous
shared
mappings created in the master before fork, so a worker inherits every
pool's
segment in its address space even though it can only ever address its own
pool's partition. That is the same exposure model as the main OPcache SHM,
which is already shared across pools today; the Static Cache is in fact
more
isolated, because it is logically partitioned per pool where the script
cache
is not. The data-leak-through-the-feature case you raised, one pool reading
another's cached values through the API, does not exist in this design. If
on
top of that we want address-space isolation, so a worker cannot even see
another pool's bytes, that is a worthwhile hardening (per-pool named
segments
mapped only in that pool's children, or unmapping the others post-fork),
and I
am happy to do it as a follow-up if you consider it in scope.

Your single-pool suggestion would also work, but per-pool partitions keep
the
feature usable for the multi-pool shared-hosting setups where a
single-cache
design would otherwise be unacceptable.

Timo: thanks for the immutable_cache pointer

See also Tyson's php-immutable_cache [...] related APCu discussions

Thank you. Tyson told me about immutable_cache himself a while ago, and
it
shaped my thinking here. I built an internal extension along the same
lines,
colopl_cache, an APCu-style drop-in for immutable values. What that work
showed me is that the parts that matter most for this use case (OPcache
compatibility, behaviour under a JIT-heavy workload, and the Zend VM
intervention needed for static-state caching) are very hard to get right
as an
ordinary extension. That is why I brought this to OPcache as an RFC
instead of
shipping another extension: it needs cooperation from the engine, the VM,
and a
few internal classes that an extension cannot coordinate cleanly. So the
prior
art is genuinely appreciated; it is part of how I arrived here.

Best regards,
Go Kudo

Thanks,

Larry's right, I'm just one reviewer among others. I'm raising the points I
make not as rebuttals but as food for thought for everybody interested
also. And I'm interested in reading what others think about the points I
make, especially the object-serialization part.

I take no criticism of deepclone at all when you improve your
implementation.

I submitted a PR on your fork [1] with a significant cleanup of the
implementation, basically removing the serialize fallback when copying into
SHM. That drops entirely the need for getCacheStoreType() and its enum,
which exposed internal concerns anyway.
The result is both faster, a win for all.

What remains to me (in no specific order):

1. Reserved keys and the FQCN rejection. set()/get() still reject keys
   starting with the reserved prefixes and reject loaded class names, and
   delete() still takes $key_or_class, because of the attributes. That's leaky
   to me.

2. Accepting objects at all - aka implicit serialize on set(), which I
   argued as something leaky also to me. I appreciate that you showed that
   doing this in one go provides some perf benefits over my two steps
   approach. My abstraction-related arguments still stand and I'd be happy to
   see what others think about this.

3. static methods - see Larry's reply

4. Attributes. You kept them as "ergonomic surface, no new storage model",
   but that does not answer the cost I raised: the JIT paths, the VM hooks,
   and the CacheStrategy::Tracking machinery exist only for the attribute
   case, and the reserved-key leak in #1 is their concrete footprint on the
   explicit API. None of that is needed by the explicit cache. That is exactly
   why I would split them into a follow-up: the explicit cache can land and be
   reviewed on its own, while the attribute semantics (cross-request shared
   mutable state, mutation tracking) get the separate scrutiny they deserve.
   Bundled, they couple the review of a simple primitive to the riskiest part
   of the patch.

5. Pinned/non-volatile I remain unconvinced. You proved that "materialize
   once per worker, then a near-zero static read per request" is something
   per-request hydrate cannot match. That is real but it is narrow. If one
   cares about perf that much, then moving to a worker-based runtime model
   (aka FrankenPHP workers) provides way more evident perf improvement and
   doesn't need pinning at all since there, static properties are live for a
   worker-long duration.

I feel like it could be easier for everybody to agree on a tighter RFC and
that's what I'm trying to help figure out - the MVP of your proposal.

Again, I'd be happy to read more feedback from others now that I laid my
current stand.

Thanks,
Nicolas

[1] https://github.com/colopl/php-src/pull/4

Hi,

Hi internals and All OPcache Static Cache RFC discussion members.

I've made significant changes to the API to bring it to a form that most
people will find acceptable.
Currently the implementation stub is here

https://github.com/colopl/php-src/blob/982a5f4d6bffd033f9c5a02586327c86fcef1cda/ext/opcache/opcache.stub.php

And thank you Nicolas, Hi's more optimization and simplification bring
better performance and simplism.
This means you ever have to worry about how values are stored anymore.
Serializer is completely gone.
https://github.com/colopl/php-src/pull/4

I sent this email because I wanted to hear thoughts on whether
I should decide to remove the proposed implementation of Attribute based
cache from this RFC.

Attribute-based caching is highly efficient and consistently delivers the
best performance.
But, it also requires the OPcache JIT to intervene.

This requires a review by Derick, the developer of JIT, and must be
handled with caution.

I think you mean Dmitry.

Furthermore, the argument that FrankenPHP should be used if that level of
performance is required certainly makes sense.

Originally, I drafted this RFC with the goal of “improving performance as
an extension of the existing PHP SAPI,”
so this would deviate from my initial objective. However, now that I
realize there is a demand for a “more faster integrated APCu,”
I feel that this goal might need to be deprioritized.

This RFC also sparked a discussion about how security boundaries should be
handled.
I’ve chosen to implement it in a way that SAPI isn’t enabled unless
explicitly opted into
Do you think this meets the requirements? (I’d especially like to ask
Jakub about this.)

Unfortunately I don't currently have much time as I need to spend all my
time on stream (we have got quite tight deadline for it). The soonest I can
properly spend time on this would be October.

To explain the process step by step, here is how I would like to proceed:

1. Narrow the scope of this RFC, reach consensus and hold a vote as soon
   as possible, and ensure it can be incorporated into 8.6.
2. Create a new RFC on Attribute-based Caching to initiate a new
   discussion (though this may not be ready in time for 8.6.)

It depends on other reviewers as well but I think 8.6 might be a bit too
optimistic for this considering the implementation size a potentially
security impact if it doesn't work correctly.

Kind regards,

Jakub

2026年6月8日(月) 20:09 Tim Düsterhus tim@bastelstu.be:

Konnichiwa

Am 2026-05-16 17:19, schrieb Go Kudo:

RFC: https://wiki.php.net/rfc/opcache_static_cache
Implementation: https://github.com/php/php-src/pull/22052

Thank you for your RFC. I am seeing there already was discussion and
changes to the RFC. This seems to have resulted in some inconsistencies.

The "Proposal" section still mentions "the volatile cache, used by
OPcache\volatile_* […]", but these functions have been renamed. The same
applies to the next bullet point for the pinned cache and to the "Why
two cache backends" section. Maybe there is even more places where the
old function names are referenced.

I also noticed some problems with the "Coding Standards and Naming
Policy"
(https://github.com/php/policies/blob/main/coding-standards-and-naming.rst).

Namely:

1. The namespace should be called Opcache for proper PascalCase.
2. The CacheStoreType cases should follow PascalCase, so
   OpcacheSerialized and PhpSerialized.
3. There must be a OpcacheException base exception: class OpcacheException extends Exception { }.
4. StaticCacheException must extend from the OpcacheException.
5. The policy does not say anything about properties, but it is
   generally accepted that properties should also use camelCase instead of
   underscores. So it needs to be $startupFailed instead of
   $startup_failed and similar.

I'm still working through the full RFC and the discussion. From what I
see the points above are still valid in the latest version of the RFC
and the discussion. That is why I am already sending them now.

Best regards
Tim Düsterhus

こんにちは Tim, お世話になっています
I have recovered my health thanks to the medication. :)

Currently implementation has 3.0.0, but RFC document version is 2.0.0,
Document is stale status.

I'm appealing to the Remove Attribute function currently, Attribute
implementation requires the change of JIT implementations.
But currently do not respond to ML members. I stopped updating RFC
documents and implementations.
(Sorry for my bad English, I didn't say this with the intention of
criticizing the ML members.)

I've implemented this as a pure PHP extension for use at my company. but
performance is too bad compared
to this RFC implementation.

I understand there are security concerns associated with SHM sharing, and I
believe I addressed these through
an opt-in process on the SAPI side. I would appreciate your feedback on
whether this is a sufficient solution.

If I were to implement Attribute, this RFC would provide a very fast and
efficient cache, but do you think we could get Dmitry's approval?
(Derick, I apologize for getting your name wrong,)

What is the best option I can offer right now? For now, I want to implement
this RFC in a way that everyone desires.

Best regards,
Go Kudo