On the PHP Manual Masterpieces site has a recent post looking at PBKDF and PHP (and, more specifically, the information that's presented about it in the manual).

So why are we here? Well, a faithful follower slipped me a tip to check out the documentation. It turned out I agreed: I don’t like it. [...] Let’s be clear: I have read the backing C code of this feature and I see nothing wrong with the actual functionality. My issues are strictly with the documentation and the API, both of which are very PHP-ish in the sorts of ways that drive me to hateblog about a programming language on a Friday night. It turns out there are people who are totally okay with these design decisions, and I can’t help that their subjective tastes are wrong, but that’s just how it is.

She mentions three different major issues with the documentation currently in the manual:

• Non-copypaste-safe cryptography
• The fact that PHP does not fail effectively when it comes to cryptographic handling
• The lack of units defined (like for the "length" parameter of hash_pbkdf2)