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