Description
Summary
Propose extending the file-level declare() mechanism to allow (1) per-file OPcache control and (2) a file-level PHP-target hint (e.g., php_target=8). These declarations would be parsed at compile/request time and provide safer, localized control for hot-reload, development workflows and gradual migration to newer PHP semantics.
Motivation
OPcache configuration today is global (php.ini / SAPI) or requires runtime API calls. That forces deploy-time or process-level changes for behaviors that developers often want only for a single file or script (hot-update script, migration shim, dev helper).
Mixed codebases and staged migrations to PHP 8+ would benefit from a per-file hint that signals intended target semantics to static checkers and to the runtime so tooling and warnings are easier to provide.
Proposal (syntax examples)
Extend declare() to accept structured file-level directives. Example syntaxes (illustrative):
declare(strict_types=1, opcache={"validate_timestamps":1, "revalidate_freq":0});
declare(opcache_validate=1, opcache_revalidate_freq=0);
declare(php_target=8);
Semantic meaning:
opcache.* options apply to the current file’s handling by the engine: controlling whether the engine should validate timestamps for this file, the revalidation frequency, or temporarily bypass caching for this file during request processing.
php_target indicates the file’s intended PHP major version semantics (informational/diagnostic), enabling static analyzers or runtime to warn about compatibility issues.
Behavior and scope
Declarations are file-scoped: they affect only the file (and optionally its immediate include context) and should not change global ini persistently.
Engine should honor supported options where possible; if unsupported or disabled for policy reasons, the engine should ignore the declaration and optionally log a warning (configurable).
For cache consistency, declarations must be considered part of the cache key or the engine must ensure declarations are enforced when executing cached scripts.
Compatibility & safety
Backward compatible: older engines simply ignore unknown declare options.
Declarations that cannot be honored must not break execution; they may log diagnostic messages for developers/ops.
Declarations do not change behaviour across requests or processes unless the engine explicitly implements a request-scoped override.
Implementation notes (high-level)
Parser: extend grammar to accept new declare forms and attach metadata to the compiled AST/opcache entry.
OPcache integration: at load/compile-time the engine may temporarily override validation behavior for that file or encode the declaration into the cached entry so execution respects the request-scoped policy.
Realpath/caching: ensure cache keys canonicalize file path and include declaration metadata where necessary to avoid stale cache issues.
Diagnostics: opcache_invalidate() and related APIs should provide diagnostic detail when declare-directed behavior cannot be applied (e.g., not cached, invalid path, extension disabled).
Use cases
Hot-update script that must always load latest source: declare(opcache_validate=1, opcache_revalidate_freq=0); at file top.
Gradual migration: annotate migrated files with declare(php_target=8); to let linters and runtime warn if executed on lower PHP versions.
Shared hosting: allow site owners to set file-level validation without global php.ini edits.
Rationale
Localized control reduces the friction of development and hot-update workflows, reduces the need for process restarts on deploy, and makes migration safer by allowing file-level semantic hints.
Suggested basic issue text (short)
Please add a file-level declare() extension to control opcache validation per-file and to provide an optional php_target file-level hint. This improves developer experience for hot-updates and migrations while remaining backward-compatible.
Description
Summary
Propose extending the file-level declare() mechanism to allow (1) per-file OPcache control and (2) a file-level PHP-target hint (e.g., php_target=8). These declarations would be parsed at compile/request time and provide safer, localized control for hot-reload, development workflows and gradual migration to newer PHP semantics.
Motivation
OPcache configuration today is global (php.ini / SAPI) or requires runtime API calls. That forces deploy-time or process-level changes for behaviors that developers often want only for a single file or script (hot-update script, migration shim, dev helper).
Mixed codebases and staged migrations to PHP 8+ would benefit from a per-file hint that signals intended target semantics to static checkers and to the runtime so tooling and warnings are easier to provide.
Proposal (syntax examples)
Extend declare() to accept structured file-level directives. Example syntaxes (illustrative):
declare(strict_types=1, opcache={"validate_timestamps":1, "revalidate_freq":0});
declare(opcache_validate=1, opcache_revalidate_freq=0);
declare(php_target=8);
Semantic meaning:
opcache.* options apply to the current file’s handling by the engine: controlling whether the engine should validate timestamps for this file, the revalidation frequency, or temporarily bypass caching for this file during request processing.
php_target indicates the file’s intended PHP major version semantics (informational/diagnostic), enabling static analyzers or runtime to warn about compatibility issues.
Behavior and scope
Declarations are file-scoped: they affect only the file (and optionally its immediate include context) and should not change global ini persistently.
Engine should honor supported options where possible; if unsupported or disabled for policy reasons, the engine should ignore the declaration and optionally log a warning (configurable).
For cache consistency, declarations must be considered part of the cache key or the engine must ensure declarations are enforced when executing cached scripts.
Compatibility & safety
Backward compatible: older engines simply ignore unknown declare options.
Declarations that cannot be honored must not break execution; they may log diagnostic messages for developers/ops.
Declarations do not change behaviour across requests or processes unless the engine explicitly implements a request-scoped override.
Implementation notes (high-level)
Parser: extend grammar to accept new declare forms and attach metadata to the compiled AST/opcache entry.
OPcache integration: at load/compile-time the engine may temporarily override validation behavior for that file or encode the declaration into the cached entry so execution respects the request-scoped policy.
Realpath/caching: ensure cache keys canonicalize file path and include declaration metadata where necessary to avoid stale cache issues.
Diagnostics: opcache_invalidate() and related APIs should provide diagnostic detail when declare-directed behavior cannot be applied (e.g., not cached, invalid path, extension disabled).
Use cases
Hot-update script that must always load latest source: declare(opcache_validate=1, opcache_revalidate_freq=0); at file top.
Gradual migration: annotate migrated files with declare(php_target=8); to let linters and runtime warn if executed on lower PHP versions.
Shared hosting: allow site owners to set file-level validation without global php.ini edits.
Rationale
Localized control reduces the friction of development and hot-update workflows, reduces the need for process restarts on deploy, and makes migration safer by allowing file-level semantic hints.
Suggested basic issue text (short)
Please add a file-level declare() extension to control opcache validation per-file and to provide an optional php_target file-level hint. This improves developer experience for hot-updates and migrations while remaining backward-compatible.