Hi all,
I've been off the lists for a bit (6 or 7 years, it seems) so for
anybody who remembers me, hi! . . .and for anybody who doesn't remember
me, hi! I used to work quite a lot on the docs and even had a couple of
small code commits to my credit. Anyway, I'm back.
I've been getting back into documentation and working through the open
doc bugs and came across one which is a little hard to document as
currently implemented: http://bugs.php.net/bug.php?id=49038 (in brief:
the default value for the maxlen param is documented as -1, but
internally it is in fact PHP_STREAM_COPY_ALL and passing -1 as maxlen
simply errors out.
This seems to stem from a patch a couple of years back originating from
this bug report: http://bugs.php.net/bug.php?id=41430
I see the reason behind the patch but to be honest, documenting this is
uncomfortable because I'd have to put in that the default value is
something which cannot be represented in a PHP script. Which in itself
isn't a huge deal except that it does mean that you can't (cleanly)
write code to call file_get_contents() for you since there is no value
of $maxlen for which $file = file_get_contents($fname, $flags, $context,
$offset, $maxlen); can be made to work--you'd have to wrap it in a
conditional. It also isn't consistent with, for instance,
stream_get_contents().
I would propose something like this:
Index: ext/standard/file.c
--- ext/standard/file.c (revision 288076)
+++ ext/standard/file.c (working copy)
@@ -541,8 +541,8 @@
return;
}
- if (ZEND_NUM_ARGS() == 5 && maxlen < 0) {
-
php_error_docref(NULL TSRMLS_CC, E_WARNING, "length must be greater
than or equal to zero");
- if (ZEND_NUM_ARGS() == 5 && maxlen < PHP_STREAM_COPY_ALL) {
-
php_error_docref(NULL TSRMLS_CC, E_WARNING, "length must be greater
than or equal to -1");
RETURN_FALSE;
}
. . .so that I don't have to document maxlen with something along the
lines of "actually, this is -1 internally but you can't represent that
in your script".
Not a biggie but one way or the other I'd like to get this documented
and this seems to me to be the cleanest way to solve the problem.
(Obviously it would still need to be documented that it is an
unrepresentable value in version 5.2.3 through 5.3.0.
Thoughts? Changes? Or should I just document it as one of those weird
things?
Torben