[Xapian-discuss] Understanding API Documentation for PHP

[Peter Van Dijk]

> As Peter says, it's really just that you're talking to a more strongly
> typed
> language.
>
> We could override this with some effort, but I'm not sure it's worthwhile -
> typically you don't want to be passing a number as a term, so I think it's
> more likely to hide bugs than help users.  It's easy to say "yes, I really
> did want to do that".
>
> But I'm surprised that Peter says "a lot" - perhaps there are cases where
> we should be doing this.  Some concrete examples would be useful rather
> than just talking in generalities.
>
>
I probably gave the wrong impression sorry - the issues i had seemed to be a
couple of methods only, the 'a lot' was a reference to that i used them
frequently. I think what i wanted to get across is that, unless you actually
stop and think about what types you're passing from PHP (which, when you've
spent too much time in PHP world, you start to forget), you just naturally
run into these issues.

As for concrete examples, there's only 2 that come to mind:

- In 1.2.6 wdf/termcount values in TermGenerator accepted floats from php
(presumably implicitly converted to integers), in 1.2.7 the same code throws
errors. (From a strict typing point of view, the 1.2.7 behavior is correct,
however)
"Normal" behavior in PHP (that is to say, the behavior i would have
expected), would be to throw a PHP notice, and implicitly convert the values
back to an int.

- Using Query(OP_VALUE_RANGE) takes strings for the begin and end
parameters, calling it with ints in PHP causes errors - "Most" PHP modules
would automatically convert these parameters as strings even if you pass
them as integer values.
The way that MySql and PHP work together means that data returned from MySql
is typically a string, regardless of the real data type is, meaning a lot of
integer values are string types unless explicitly cast as something else.
For the sake of my own code, i cast these values back to integers where
required (such that, for example, if you have zzz_id you know it's gonna be
an int not a string). Similarly, the constants i use to pass to Query in
most circumstances are int, so i need to cast my constants to a string to
pass through.

Neither of these is a big issue for me (or anyone, generally, i would
think), it just means i cant get away with sloppy coding and implicit type
conversions in my own code. I've probably used strval( ) half a dozen times
in 10 years until i wrote my xapian classes, and now i have a hundred calls
in there just to make everything type safe since i pass a lot of integers
around. The majority of PHP modules hide this kind of thing from the
programmer by doing conversions if/when required - particularly for int
to/from string.

I think the overall issue is that, when you run into these problems, rather
than throwing a PHP warning / notice / error saying that you're doing it
wrong, you end up with a method overloading error which gives you no
indication as to what's really happening. (PHP has a very nieve concept of
overloading methods because it's so loosely typed)