Re: svn: /phpdoc/en/trunk/reference/filesystem/functions/ file-get-contents.xml
| From: | Peter Cowburn | Date: | Wed, 28 Apr 2010 12:43:52 +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-6505@lists.php.net to get a copy of this message | ||
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
>