includes/Support/class-filesystem.php
Filesystem boundary — directories, local-path resolution, minify path policy, atomic writes, verified PHP writes, and cache-path containment guards.
Class Filesystem
Class Filesystem
final class FilesystemProperties
| Property | Visibility | Type | Default | Line |
|---|---|---|---|---|
$normalized_host_cache | private static | array | array() | 66 |
$minify_roots_cache | private static | array | array() | 81 |
$purge_fallback_memo | private static | array | array() | 98 |
$home_url_cache | private static | array | array() | 2364 |
publicstatic clear_purge_fallback_memo()
public static function clear_purge_fallback_memo(=null $blog_id): voidClear the purge-fallback gate memo (testing isolation, settings save). Parameter Type Default Description $blog_id=null— Optional blog ID to clear. Null clears all.
Return: void.
publicstatic prepare_cache_dir()
public static function prepare_cache_dir($cache_dir): boolRecursively creates cache directory if not exists. Parameter Type Default Description $cache_dirstring— Path to the cache directory.
Return: bool — True if created or exists, false otherwise.
publicstatic init_filesystem()
public static function init_filesystem()Initializes the WP_Filesystem API.
Return: mixed — WP_Filesystem_Base|false The filesystem object or false on failure.
publicstatic get_local_path()
public static function get_local_path(string $url): stringGets the local file path from a URL. Parameter Type Default Description $urlstring— The URL to process.
Return: string — The local file path.
publicstatic get_minify_allowed_roots()
public static function get_minify_allowed_roots(): arrayGets the allow-listed filesystem roots for minify/combine file serving.
Return: string[] — Normalized absolute root paths.
publicstatic reset_minify_roots_cache()
public static function reset_minify_roots_cache(): voidReset the minify-roots memo (testing isolation).
Return: void.
publicstatic is_minify_path_allowed()
public static function is_minify_path_allowed($path): boolWhether a minify/combine source path is allowed to be read. Parameter Type Default Description $pathmixed— Candidate filesystem path.
Return: bool — True when the path resolves inside an allowed root.
publicstatic validate_minify_path()
public static function validate_minify_path($path): stringValidates a minify/combine source path and returns its resolved form. Parameter Type Default Description $pathmixed— Candidate filesystem path.
Return: string — Resolved allowed path, or \’\’ when rejected.
publicstatic get_js_css_minified_file()
public static function get_js_css_minified_file()Gets the number of minified JS and CSS files.
Return: array — Associative array with counts for JS and CSS files.
publicstatic normalize_cache_host()
public static function normalize_cache_host(string $raw_host): stringNormalize a raw host value into a safe cache-key domain. Parameter Type Default Description $raw_hoststring— Raw host value (e.g. $_SERVER[\’HTTP_HOST\’] or a home_url() host).
Return: string — Normalized lowercase host, or \’\’ when invalid.
privatestatic memoize_normalized_host()
private static function memoize_normalized_host(string $raw_host, string $normalized): stringStore a normalized host in the per-value memo (bounded size). Parameter Type Default Description $raw_hoststring— Raw input key. $normalizedstring— Normalized result.
Return: string — The normalized result (passthrough for `return` sites).
publicstatic reset_normalized_host_cache()
public static function reset_normalized_host_cache(): voidReset the normalized-host memo (testing isolation).
Return: void.
publicstatic sanitize_cache_url_path()
public static function sanitize_cache_url_path(?string $url_path, ?string=null $allowed_host): stringSanitize a URL path for cache file mapping. Parameter Type Default Description $url_path?string— Raw URL path or URL. $allowed_host?string=null— Optional canonical host (alias: $domain / $canonical_host at call-sites); same-host absolute URLs map to their path, others refuse.
Return: string — Sanitized relative path or empty string.
publicstatic is_cache_path_contained()
public static function is_cache_path_contained(string $cache_root_dir, string $domain, string $path): boolWhether an absolute path stays inside the cache tree. Parameter Type Default Description $cache_root_dirstring— Absolute cache root directory. $domainstring— Canonical domain directory segment. $pathstring— Absolute file or directory path to check.
Return: bool — True when contained.
publicstatic is_realpath_contained()
public static function is_realpath_contained(string $cache_root_dir, string $domain, string $path): boolSymlink-aware containment check for cache write targets. Parameter Type Default Description $cache_root_dirstring— Absolute cache root directory. $domainstring— Canonical domain directory segment. $pathstring— Absolute file or directory path to check.
Return: bool — True when contained.
publicstatic resolve_realpath()
public static function resolve_realpath(string $lexical_path): ?stringResolve a path via realpath(), keeping the lexical remainder. Parameter Type Default Description $lexical_pathstring— Normalized absolute path to resolve.
Return: string|null — Resolved absolute path, or null when unresolvable.
publicstatic validate_cache_write_path()
public static function validate_cache_write_path(string $cache_root_dir, string $domain, string $path): boolSingle-call validator for absolute cache write targets. Parameter Type Default Description $cache_root_dirstring— Absolute cache root directory. $domainstring— Canonical domain directory segment. $pathstring— Absolute file path to validate.
Return: bool — True when the target may be written.
publicstatic is_htaccess_path_allowed()
public static function is_htaccess_path_allowed(string $htaccess_file): boolWhether an .htaccess target may be written by the plugin. Parameter Type Default Description $htaccess_filestring— Absolute .htaccess path candidate.
Return: bool — True when the target may be written.
publicstatic sanitize_cache_path()
public static function sanitize_cache_path(string $cache_root_dir, string $domain, $url_path_or_url, string $filename): stringBuild a contained absolute cache file path from its parts. Parameter Type Default Description $cache_root_dirstring— Absolute cache root directory. $domainstring— Canonical domain directory segment. $url_path_or_urlstring|null— Raw URL path or URL. $filenamestring— File name (e.g. `index.html`).
Return: string — Contained absolute path, or \’\’ when refused.
publicstatic atomic_tmp_path()
public static function atomic_tmp_path(string $final_path): stringBuild a unique sibling tmp path for atomic writes. Parameter Type Default Description $final_pathstring— Final file path the tmp sits beside.
Return: string — Tmp sibling path (\’\’ when input is empty).
publicstatic atomic_file_put_contents()
public static function atomic_file_put_contents($fs, string $path, string $contents): boolAtomically write contents via tmp-file + rename. Parameter Type Default Description $fsmixed— Filesystem object exposing put_contents()/move()/delete(). $pathstring— Final file path. $contentsstring— File contents.
Return: bool — True on success.
publicstatic verify_php_syntax()
public static function verify_php_syntax(string $code, string=\'\' $tmp_file_for_lint): boolCheck that PHP code parses without a syntax error. Parameter Type Default Description $codestring— PHP source to check. $tmp_file_for_lintstring=\'\'— Optional tmp file holding $code for `php -l`.
Return: bool — True when the code looks parseable.
privatestatic php_brackets_balanced()
private static function php_brackets_balanced(array $tokens): boolCheck that structural brackets are balanced in a token stream. Parameter Type Default Description $tokensarray— Token stream from `PhpToken::tokenize()`.
Return: bool — True when every bracket type is balanced and ordered.
publicstatic atomic_write_php_verified()
public static function atomic_write_php_verified($fs, string $path, string $contents, =null $expect): ?boolAtomically write PHP source with syntax verification and rollback. Parameter Type Default Description $fsmixed— Filesystem object exposing exists()/get_contents()/put_contents()/move()/copy()/delete(). $pathstring— Final file path. $contentsstring— New file contents. $expect=null— Optional assertion receiving contents, returning bool.
Return: bool|null — True on verified success, false on verified failure, null when unsupported.
privatestatic restore_php_backup()
private static function restore_php_backup($fs, string $path, string $original, int $chmod): boolRestore a PHP file from its in-memory original or `.wppo-bak` backup. Parameter Type Default Description $fsmixed— Filesystem object. $pathstring— Final file path. $originalstring— In-memory original contents (\’\’ when none). $chmodint— File mode for a direct-write restore.
Return: bool — True when a restore write/copy was issued.
privatestatic delete_php_backup()
private static function delete_php_backup($fs, string $path): voidBest-effort deletion of the `.wppo-bak` backup beside a PHP file. Parameter Type Default Description $fsmixed— Filesystem object. $pathstring— Final file path (backup is `$path.wppo-bak`).
Return: void.
publicstatic is_purge_fallback_enabled()
public static function is_purge_fallback_enabled(): boolWhether the post-purge last-good fallback is enabled.
Return: bool — True when purge-fallback retention/serving is active.
publicstatic get_purge_fallback_path_for()
public static function get_purge_fallback_path_for(string $file_path): stringMap a derived asset path to its sibling last-good fallback path. Parameter Type Default Description $file_pathstring— Absolute derived-asset path.
Return: string — Sibling fallback path, or \’\’ when not applicable.
publicstatic retain_purge_fallback_file()
public static function retain_purge_fallback_file($fs, callable $is_allowed, string $file_path): voidRetain a last-good fallback copy before a derived file is purged. Parameter Type Default Description $fsobject— Filesystem exposing exists()/size()/copy()/get_contents()/put_contents(). $is_allowedcallable— Containment validator: fn( string $path ): bool. $file_pathstring— The derived file about to be deleted.
Return: void.
publicstatic is_purge_fallback_payload_valid()
public static function is_purge_fallback_payload_valid($fs, string $fallback): boolWhether a retained fallback file holds a servable payload. Parameter Type Default Description $fsobject— Filesystem exposing size()/get_contents(). $fallbackstring— Absolute fallback path.
Return: bool — True when the fallback exists with non-empty content.
publicstatic get_staged_path_for()
public static function get_staged_path_for(string $file_path): stringMap a derived CSS/JS file to its sibling staged-rollout path. Parameter Type Default Description $file_pathstring— Absolute live derived-file path.
Return: string — Sibling staged path, or \’\’ when not applicable.
publicstatic promote_staged_file()
public static function promote_staged_file($fs, callable $is_allowed, string $live_path): boolPromote a staged-rollout file over its live sibling (issue #1348). Parameter Type Default Description $fsobject— Filesystem exposing exists()/size()/get_contents()/move()/copy()/delete(). $is_allowedcallable— Containment validator: fn( string $path ): bool. $live_pathstring— Absolute live derived-file path.
Return: bool — True when the staged file replaced the live file.
publicstatic restore_fallback_file()
public static function restore_fallback_file($fs, callable $is_allowed, string $live_path): boolRestore a derived file from its retained last-good fallback (issue #1348). Parameter Type Default Description $fsobject— Filesystem exposing copy()/delete() plus the fallback-validity surface. $is_allowedcallable— Containment validator: fn( string $path ): bool. $live_pathstring— Absolute live derived-file path.
Return: bool — True when the fallback payload replaced the live file.
publicstatic describe_rollout_slot()
public static function describe_rollout_slot($fs, string $live_path): arrayDescribe the safe-rollout slot triple for a live file (issue #1348). Parameter Type Default Description $fsobject— Filesystem exposing exists()/size()/get_contents(). $live_pathstring— Absolute live derived-file path.
Return: array{live_bytes: — int, live_checksum: string, staged: bool, staged_bytes: int, staged_checksum: string, staged_changed: bool, fallback: bool} Slot description.
publicstatic purge_fallback_should_log()
public static function purge_fallback_should_log(): boolA single blog-prefixed transient (`wppo_purge_fallback_served`) gates all fallback-serve log rows (both Cache and used-CSS share it) so a post-purge miss storm writes one row per day instead of one per directory.
Return: bool — True when the caller should write its log row.
publicstatic css_file_valid()
public static function css_file_valid(string $path): boolWhether a generated CSS file is valid (exists, readable, non-empty). Parameter Type Default Description $pathstring— Absolute path to the CSS file.
Return: bool — True when the file is usable.
publicstatic log_css_fallback()
public static function log_css_fallback(string $reason, array $handles, string $context): voidLog a guarded CSS fallback (combine or used-CSS) event with throttling. Parameter Type Default Description $reasonstring— Machine-readable reason code (empty_payload, write_failure, head_match_failure, …). $handlesarray— Handles preserved by the fallback. $contextstring— \’combine\’ or \’usedcss\’ — selects the log-key prefix and message.
Return: void.
privatestatic home_url_for_local_path()
private static function home_url_for_local_path(): stringResolve the untrailed home URL with a per-blog memo.
Return: string — Untrailed home URL, or \’\’ when unavailable.
publicstatic reset_home_url_cache()
public static function reset_home_url_cache(): voidReset the home-URL memo (testing isolation / switch_to_blog).
Return: void.
privatestatic min_cache_dir_for_counts()
private static function min_cache_dir_for_counts(): stringCurrent site\’s blog-scoped minify cache directory.
Return: string — Normalized absolute path to the site-scoped min cache dir.
Hooks
Hooks referenced in includes/Support/class-filesystem.php: Hook Type Line Notes wppo_minify_allowed_rootsfilter 333 — wppo_allow_php_lintfilter 1367 — wppo_purge_fallback_enabledfilter 1683 @param ×1