Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:45493
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.222.174 as permitted sender)
DomainKey-Status: bad
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=sender:message-id:date:from:reply-to:user-agent:mime-version:to
         :subject:content-type:content-transfer-encoding;
        b=wTfxUfdT7R4Ef44KiTJMstrqJGK0atK0e7n3WZ5A41Oi/eQMVQ7WXd/r9577MQq+1m
         WumDbnutK6qVz6IjgiedWacntQtDFNLIFasjVtxc0M5RBkb6QfrEaZ2wYJQvAn+h3Beu
         3qYtTKslKrJskZ0JNheAPUHMvOZZ3zYEe+MbA=
Sender: Lars Torben Wilson <larstorben@gmail.com>
Message-ID: <4AA1F853.5060309@php.net>
Date: Fri, 04 Sep 2009 22:34:11 -0700
Reply-To: torben@php.net
User-Agent: Thunderbird 2.0.0.23 (X11/20090817)
MIME-Version: 1.0
To: internals@lists.php.net
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Hi again! . . .and file_get_contents() maxlen default value
From: torben@php.net (Lars Torben Wilson)

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