Re: [PDO] PDO docs and spec problem

On 26.10.2009, at 12:44, Oskar Eisemuth wrote:

> I do think the comments for the various PDO functions can be helpful  
> to specific the needs or the workarounds people need to use.
> There is a general lack of documentation how flags interact, what  
> flags belongs to what kind of query, this makes users (including me)  
> not very happy.
> Guess work how a function or flag works should be avoided, no  
> surprises please!

<snip>

> About PDO_FETCH_UNIQUE I am unsure, at least my tests today showed  
> that pdo mysql show a new behaviour, it works without  
> PDO_FETCH_GROUP and results in something like MDB2/DB getAssoc. I am  
> quite sure my last tests with php < 5.3 assumed GROUP in the past.  
> Now I would really like to use that feature, but how stable is it  
> when the user documentation and code assumes PDO_FETCH_GROUP should  
> be used?!?

Yeah, I also find this fairly hard to use. I cannot remember which  
combination gets me what. However the API as it is is very extensible.  
I mean we have quite a lot of different fetch modes and they all fit  
into this API without having a bazillion optional parameters. Named  
parameter support in core could solve the situation, but we do not  
have that.

One approach could be to provide some additional flags that combine  
common use cases, but that might in the end just aggrevate the issue.

> (It doesn’t mention it kills the first column in the result set, I  
> would like to have it for creating an ORM object; And now I already  
> ask for a feature improvement, sorry)

There are code examples for a fair number of them, but still not ideal.

> Is PDO_FETCH_KEY_PAIR even documented somewhere? The comment in the  
> header file doesn’t mention that you really need to have only two  
> columns.
>
> I think this description of PDO::FETCH_SERIALIZE is technical wrong.:
> Docs say: “As PDO::FETCH_INTO but object is provided as a serialized  
> string. Available since PHP 5.1.0.”
> The PDO code seems to agree with me that it really belongs to  
> FETCH_CLASS.
>
> Before new features and bug fixing can be done, I think the  
> documentation of PDO needs love. If you use the PDO docs as specs  
> how PDO should work then new bugs will be introduced.
>
> A new wiki page would be a useful starting point to cleanly describe  
> the behaviour of various flags and how they work (together)?


In general we have said we do not really want to use the wiki to  
document things, even for temporary use .. because temporary becomes  
permanent. However we can use it to at least keep a todo list of  
things that still need to be documented.

regards,
Lukas Kahwe Smith
[email protected]