Re: svn: /phpdoc/en/trunk/reference/filesystem/functions/ file-get-contents.xml

From: Date: Wed, 28 Apr 2010 11:57:30 +0000
Subject: Re: svn: /phpdoc/en/trunk/reference/filesystem/functions/ file-get-contents.xml
References: 1 2 3 4 5 6 7 8 9 10  Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-6504@lists.php.net to get a copy of this message
On 28 April 2010 12:03, Peter Cowburn <salathe@php.net> wrote: > On 28 April 2010 10:58, Richard Quadling <rquadling@googlemail.com> wrote: >> On 27 April 2010 19:11, Philip Olson <philip@roshambo.org> wrote: >>> On Apr 27, 2010, at 8:59 AM, Richard Quadling wrote: >>>> On 27 April 2010 16:52, Richard Quadling <rquadling@googlemail.com> wrote: >>>>> On 27 April 2010 16:05, Hannes Magnusson <hannes.magnusson@gmail.com> >>>>> wrote: >>>>>>>>> When was that argument renamed again? >>>>>>>>> Its called flags in 5.3 atleast.. >>>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> http://svn.php.net/viewvc/php/php-src/trunk/ext/standard/file.c?view=annotate#l520 >>>>>>>> >>>>>>>> http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/ext/standard/file.c?view=annotate#l521 >>>>>> >>>>>> What the proto or zpp() uses is irrelevant. >>>>>> >>>>>> bjori@jessica:~$ php --rf file_get_contents >>>>>> Function [ <internal:standard> function file_get_contents ] { >>>>>> >>>>>>  - Parameters [5] { >>>>>>    Parameter #0 [ <required> $filename ] >>>>>>    Parameter #1 [ <optional> $flags ] >>>>>>    Parameter #2 [ <optional> $context ] >>>>>>    Parameter #3 [ <optional> $offset ] >>>>>>    Parameter #4 [ <optional> $maxlen ] >>>>>>  } >>>>>> } >>>>> >>>>>>>> Both show the param as bool use_include_path and retrieve it as a >>>>>>>> 'b' >>>>>>> >>>>>>> This is why I changed the type in this commit. With these changes, the >>>>>>> description to use FILE_USE_INCLUDE_PATH conflicts somewhat if we are >>>>>>> asking people to use a boolean.  Any suggestions for the description; >>>>>>> the constant will still work since its value is 1 but should we ignore >>>>>>> that fact? What about people who might already be using >>>>>>> FILE_USE_INCLUDE_PATH? >>>>>> >>>>>> I think we should pretend that the parameter is int, called flags, and >>>>>> mention that FILE_USE_INCLUDE_PATH is defined as 1 so passing boolean >>>>>> is fine. >>>>> >>>>> >>>>> >>>>> The zpp code requires a boolean. >>> >>> I think file_get_contents() is a special case that should keep in mind FC. While >>> reverting "PHP 6" stuff, it was the one piece of documentation that required changing an >>> entire subset (parameters) of documentation, so keeping this in mind by hinting what the future >>> brings feels right. >>> >>> Hannes suggests a FC friendly fix but I wonder, are we 100% certain that BC is kept? >>> Meaning, boolean values will always work as they do today? In which case, 0,false === no flags, >>> 1,true,FILE_USE_INCLUDE_PATH === that flag, and other ints === other [future] flag combinations.. >>> How about keeping it as 'flags' and documenting it like this? >>> >>> Regards, >>> Philip >> >> If use_include_path => flags, then as long as flags is documented to >> only have 1 flag (FILE_USE_INCLUDE_PATH), then all would be fine. > > I'm inclined to vote for this approach; we do have other functions > which have only a single flag. It allows the current boolean/flag > value to be acceptable but with a nod towards more flags being > available in the future. > >> It would be nice to have the prototype correct in the code so dweebs like >> me can read the c code and at least be half way right about what is >> going on. > > Absolutely, my first port of call is usually the commented prototype > and then the source of the function that the prototype is commenting. > As this thread shows, having arguments labelled differently in > multiple places can and will confuse matters. Would changing the > source to use long/flags (from bool/use_include_path) not be a good > idea for any technical reasons, or would it be OK to do that? > >> >> Richard. Considering the only current use is a boolean test, this could easily be converted to use a mask like file_put_contents. Patch attached. -- ----- Richard Quadling "Standing on the shoulders of some very clever giants!" EE : http://www.experts-exchange.com/M_248814.html EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 ZOPA : http://uk.zopa.com/member/RQuadling

Index: file.c =================================================================== --- file.c (revision 297904) +++ file.c (working copy) @@ -518,14 +518,14 @@ } /* }}} */ -/* {{{ proto string file_get_contents(string filename [, bool use_include_path [, resource context [, long offset [, long maxlen]]]]) +/* {{{ proto string file_get_contents(string filename [, int flags [, resource context [, long offset [, long maxlen]]]]) Read the entire file into a string */ PHP_FUNCTION(file_get_contents) { char *filename; int filename_len; char *contents; - zend_bool use_include_path = 0; + long flags = 0; php_stream *stream; int len; long offset = -1; @@ -534,7 +534,7 @@ php_stream_context *context = NULL; /* Parse arguments */ - if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s|br!ll", &filename, &filename_len, &use_include_path, &zcontext, &offset, &maxlen) == FAILURE) { + if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s|lr!ll", &filename, &filename_len, &flags, &zcontext, &offset, &maxlen) == FAILURE) { return; } @@ -546,7 +546,7 @@ context = php_stream_context_from_zval(zcontext, 0); stream = php_stream_open_wrapper_ex(filename, "rb", - (use_include_path ? USE_PATH : 0) | ENFORCE_SAFE_MODE | REPORT_ERRORS, + ((flags & PHP_FILE_USE_INCLUDE_PATH) ? USE_PATH : 0) | ENFORCE_SAFE_MODE | REPORT_ERRORS, NULL, context); if (!stream) { RETURN_FALSE;
« previous php.doc.cvs (#6504) next »