Skip to content

Document touch() doesn't clear the stat cache. #4301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Document touch() doesn't clear the stat cache. #4301

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2c627b1
Document touch() doesn't clear the stat cache.
Crell Dec 13, 2024
fc2ca44
Remove unnecessary para
Crell Dec 13, 2024
6cc375b
Mention touch() in clearstatcache() page.
Crell Dec 14, 2024
0fc639a
Use existing clearstatcache note.
Crell Dec 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions reference/filesystem/functions/clearstatcache.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,9 @@
<function>filegroup</function>,
<function>fileowner</function>,
<function>filesize</function>,
<function>filetype</function>, and
<function>fileperms</function>.
<function>filetype</function>,
<function>fileperms</function>, and.
<function>touch</function>.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is wrong. This list lists the functions that read from the stat cache. touch() is a setter.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description says nothing about read/ It just says "Affected."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The context is:

When you use stat(), lstat(), or any of the other functions listed in the affected functions list (below), PHP caches the information those functions return in order to provide faster performance.

touch() is not an affected function, because it does not interact with the stat cache at all. It does not (need to) know about it.

</para>
</refsect1>

Expand Down
10 changes: 10 additions & 0 deletions reference/filesystem/functions/touch.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,16 @@ if (!touch('some_file.txt', $time)) {
<refsect1 role="notes">
&reftitle.notes;
&note.filesystem-time-res;
&note.clearstatcache;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And likewise is this change wrong.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then do we need a new entity for statcache impacting write functions? Because the root issue is I didn't realize touch didn't reset the cache, so couldn't understand why my touch() call didn't seem to do anything. So I want something on the touch page to indicate that. You and @Girgias figure out what you want there, I've already made two proposals and both of them someone has objected to.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then do we need a new entity for statcache impacting write functions?

None of them impact the statcache (except for unlink(), which automatically clears it according to the manual). But virtually all of them impact the statdata, because writes implicitly affect the mtime (and usually also the file size).

Note that exec() and friends might also affect the statdata, because you could exec('touch foo.txt'). Dom\HTMLDocument::saveHtml() does as well.

I do not see a value-add in adding a reference to the statcache to every function that possibly affects the statdata and as far as I can tell all the functions reading from the statcache have the note already.

</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably list filemtime first, because the mtime is the relevant field that is modified by touch.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

touch can modify both properties, so I listed them in alphabetical order.

<simplelist>
<member><function>clearstatcache</function></member>
<member><function>fileatime</function></member>
<member><function>filemtime</function></member>
</simplelist>
</refsect1>

</refentry>
Expand Down
Loading