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

From: Date: Wed, 28 Apr 2010 13:03:56 +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-6506@lists.php.net to get a copy of this message
On 28 April 2010 13:43, Peter Cowburn <salathe@php.net> wrote: > On 28 April 2010 12:57, Richard Quadling <rquadling@googlemail.com> wrote: >> 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. >> > > The patch looks OK to me and is pretty much what used to be there (as > far as this particular parameter is concerned) in trunk before it got > rolled back. Would there be any objections to making this change and > updating the documentation to suit? > >> >> >> >> -- >> ----- >> 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 >> > Someone will have to commit it for me to php-src. Patch attached for branches/PHP_5_3 and trunk. -- ----- 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: branches/PHP_5_3/ext/standard/file.c =================================================================== --- branches/PHP_5_3/ext/standard/file.c (revision 296669) +++ branches/PHP_5_3/ext/standard/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; Index: trunk/ext/standard/file.c =================================================================== --- trunk/ext/standard/file.c (revision 297904) +++ trunk/ext/standard/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 (#6506) next »