Re: svn: /phpdoc/en/trunk/reference/filesystem/functions/ file-get-contents.xml
| From: | Richard Quadling | 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;
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;