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

[Crell]

Thanks to @derickr for pointing this out to me. It drove me batty for days. 😄

[TimWolla]

This is not unique about touch(). None of the file operations clear the stat cache:

<?php
var_dump(filemtime('/tmp/foo.txt'), filesize('/tmp/foo.txt'));
file_put_contents('/tmp/foo.txt', str_repeat('x', random_int(0, 999)));
clearstatcache();
var_dump(filemtime('/tmp/foo.txt'), filesize('/tmp/foo.txt'));

[Crell]

Seems like we should add the same warning to other functions, then. Is it worth making an entity out of it, or just copy-paste-tweak?

[Girgias]

We already have the note.clearstatcache entity. Is that insufficient?

[Crell]

What is insufficient is my awareness that entity already exists. 😄 Switched to using that, and added touch to the list on the clearstatcache page, which was missing.

[TimWolla]

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

[Crell]

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

[TimWolla]

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.

[TimWolla]

And likewise is this change wrong.

[Crell]

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.

[TimWolla]

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.

[TimWolla]

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

[Crell]

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