[doc-en] master: file_exists, is_readable, is_writable, is_executable: local files skip the stat cache (#5997)

Author: qodelicious (qodelicious) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-22T10:20:48+02:00 Commit: https://github.com/php/doc-en/commit/a641e6b538290c138828651ac2a8713eb79c5389 Raw diff: https://github.com/php/doc-en/commit/a641e6b538290c138828651ac2a8713eb79c5389.diff file_exists, is_readable, is_writable, is_executable: local files skip the stat cache (#5997) Changed paths: A reference/filesystem/entities.ent M reference/filesystem/functions/clearstatcache.xml M reference/filesystem/functions/file-exists.xml M reference/filesystem/functions/is-executable.xml M reference/filesystem/functions/is-readable.xml M reference/filesystem/functions/is-writable.xml Diff: diff --git a/reference/filesystem/entities.ent b/reference/filesystem/entities.ent new file mode 100644 index 000000000000..fe0399839a60 --- /dev/null +++ b/reference/filesystem/entities.ent @@ -0,0 +1,23 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> +<!-- + See manual.xml for XML namespaces defaults. + Keep the lines under 79 columns, to make the process of manual + translation easier, and to avoid wrap-around in some other contexts. +--> +<entities xmlns = "http://docbook.org/ns/docbook" + xmlns:xlink = "http://www.w3.org/1999/xlink" + translate = "yes"> + +<entity name="ext.filesystem.access-check-cache"> + <note> + <simpara> + For local files, the result of this function is not cached and the file + is checked again on every call. For paths using other + <link linkend="wrappers">wrappers</link> the result is cached. + See <function>clearstatcache</function> for more details. + </simpara> + </note> +</entity> + +</entities> diff --git a/reference/filesystem/functions/clearstatcache.xml b/reference/filesystem/functions/clearstatcache.xml index 6340cb8bcd5e..de085d247c65 100644 --- a/reference/filesystem/functions/clearstatcache.xml +++ b/reference/filesystem/functions/clearstatcache.xml @@ -25,13 +25,13 @@ <function>clearstatcache</function> function to clear the information that PHP caches about a file. </para> - <para> + <simpara> You should also note that PHP doesn't cache information about non-existent - files. So, if you call <function>file_exists</function> on a file that + files. So, if you call <function>is_file</function> on a file that doesn't exist, it will return &false; until you create the file. If you create the file, it will return &true; even if you then delete the file. However <function>unlink</function> clears the cache automatically. - </para> + </simpara> <note> <para> This function caches information about specific filenames, so you only @@ -60,6 +60,12 @@ <function>filetype</function>, and <function>fileperms</function>. </para> + <simpara> + <function>file_exists</function>, <function>is_writable</function>, + <function>is_readable</function> and <function>is_executable</function> + only use the cache for paths that use a wrapper other than the local + filesystem. Local files are checked directly every time. + </simpara> </refsect1> <refsect1 role="parameters"> diff --git a/reference/filesystem/functions/file-exists.xml b/reference/filesystem/functions/file-exists.xml index 31831206dae3..715d8e354c1b 100644 --- a/reference/filesystem/functions/file-exists.xml +++ b/reference/filesystem/functions/file-exists.xml @@ -87,7 +87,7 @@ if (file_exists($filename)) { <refsect1 role="notes"> &reftitle.notes; - &note.clearstatcache; + &ext.filesystem.access-check-cache; &tip.fopen-wrapper.stat; </refsect1> diff --git a/reference/filesystem/functions/is-executable.xml b/reference/filesystem/functions/is-executable.xml index 8eda8f9b2354..159fa9e0a3b2 100644 --- a/reference/filesystem/functions/is-executable.xml +++ b/reference/filesystem/functions/is-executable.xml @@ -73,7 +73,7 @@ if (is_executable($file)) { <refsect1 role="notes"> &reftitle.notes; - &note.clearstatcache; + &ext.filesystem.access-check-cache; &tip.fopen-wrapper.stat; <note> <simpara> diff --git a/reference/filesystem/functions/is-readable.xml b/reference/filesystem/functions/is-readable.xml index 375790ed1eb1..02ef23c890c1 100644 --- a/reference/filesystem/functions/is-readable.xml +++ b/reference/filesystem/functions/is-readable.xml @@ -73,7 +73,7 @@ if (is_readable($filename)) { Keep in mind that PHP may be accessing the file as the user id that the web server runs as (often 'nobody'). </para> - &note.clearstatcache; + &ext.filesystem.access-check-cache; &tip.fopen-wrapper.stat; <note> <para> diff --git a/reference/filesystem/functions/is-writable.xml b/reference/filesystem/functions/is-writable.xml index 5ee631943e1e..e32af2c5415b 100644 --- a/reference/filesystem/functions/is-writable.xml +++ b/reference/filesystem/functions/is-writable.xml @@ -76,7 +76,7 @@ if (is_writable($filename)) { <refsect1 role="notes"> &reftitle.notes; - &note.clearstatcache; + &ext.filesystem.access-check-cache; &tip.fopen-wrapper.stat; </refsect1>