I’ve been using PHP since 2003 and it’s my full time job and this doesn’t ring true. Very, very rarely is a gotcha not in the docs comment section.

> in the docs comment section.

A classic boiled frog statement.

__It's not undocumented, someone posted a comment about that bug...__

I will quietly place my face in my hands and weep to the memory of php coding I did 20 years ago.

Seems the same nonsensical masochism is still going strong.

I mean, I am by no means an expert in PHP, and in fact most of my knowledge of it comes from hating on it (or having been thrust into the unfortunate position of being the system administrator for a popular MediaWiki instance), but even in my limited experience with it from a couple lifetimes ago I know that most of the documentation for PHP is crowdsourced in the documentation comments section. That might be depressing, but that isn't what that comment was defending: it does feel likely to be true that there aren't many "unknown unknowns" waiting for you in PHP.

To me the comments section is one thing that sets PHP apart from other languages. Need to learn a new function? Go read about it on php.net, then skim the comments for edge cases.

Need to do something new in Node? Sift through a bunch of search engine spam, read a few dissenting answers on stackoverflow that refer to a previous version, eventually find a library that does what you want, written by skullM4ster2004, plug one's nose and install it.

This is a very common trope, someone who hasn't touched PHP in decades who still thinks they know anything about the language and ecosystem now.

> I will quietly place my face in my hands and weep to the memory of php coding I did 20 years ago.

You should revisit the language. PHP7 was a huge leap forward. It's a different language now.

PHP has changed a lot. You should give it a try and stop thinking of it as the same language with the same flaws it had two decades ago.

When I had to code in php I've written a css-rule for my browser to hide the user contributions to the docs, since they where often misleading if not plainly wrong.

I remember no discernible border between 'official docs stop here' and 'user contributed opinions start here'.

I can't attest to how it used to be, but now at least they are in a section labeled "User Contributed Notes". The notes can be voted up or down, so hopefully the dross sinks to the bottom.

I do agree with the sentiment though that these unofficial notes should be taken with a grain of salt. In my experience, they have been more help than hindrance.

Maybe that's how it was, but it has a clearly defined header that says "User Contributed Notes" now, with up/down vote counts on each comment.

i always found those comment sections to be so odd — fifteen year old comments about a common pitfall and the information never makes it up to the official documentation?

i suppose it's fitting for a web-centric language to crowd source its docs on a website, but does any other mainstream language do this?

Meanwhile, I find the PHP docs far more readable/accessible than almost any other language. Compared with the official Python or (shudder) Java docs, and they're far superior, IMO.

If it makes you feel any better, at least the comments are next to the documentation? Really big projects that people rely on every day -- things like Rust's Cargo or Google's Flutter -- are riddled with bugs and limitations, requiring frustrating boilerplate workarounds to make basic things work correctly, and they generally only have mention of the problems in the comments on the billion 5-10 year old open issues in their task tracker.

Clojure crowdsources "examples" (to good effect, IMO). For example: https://clojuredocs.org/clojure.core/assoc-in

The php docs are themselves a public GitHub repo, so it's a bit sad if insightful comments don't affect change in the docs

That’s just it. I have to code with the PHP docs open like some kind of arcane recipe book.

Maybe it’s the frequency that you use the language? I go maybe 5-10k loc between needing to lookup anything in the docs at all, and 5-10x that where the issue I need guidance on isn’t in the formal doc.

Much more frequently I’m looking up something related to the tools and libraries I’m using.

The only surprising thing I’ve learned about PHP at the language level in the last 6-10 months is that you can call array_filter() without a callback to cull nulls.

It could be, but I also never felt like I really got to the point you're talking about in 2 years or so of moderate usage. I've been productive in it, and it's not like I'm hung up on control flow or something. I don't hate the language either. I still have to use it from time to time, but it just doesn't seem like it makes sense for a lot of green field work due to this.

It's mostly things like parameter order for certain built-ins that aren't intuitive and/or finding built-ins I've never used or heard of because there are so many obscure ones (there are nearly six thousand) that keep me coming back. For example, how do you disable errors in a DOMDocument? It ought to be as easy as DOMDocument->setAttribute("errors", "false"), but no it's a separate function call to libxml_use_internal_errors(true). There are like five other similar function calls for this too. PHP has abstraction leaks and little inconsistencies like this everywhere.

Granted, languages with small standard libraries, like JavaScript, by contrast get an easy cop out to blame the community of various package maintainers here. But at least in that case someone can always just write a better library.

Does that only cull nulls, or also zeroes, falses and empty strings?

Anything "falsy" -- any item that, when cast to boolean results in false. So, also zeroes, falses and empty strings.

That was my point - OP said it "culls nulls", and the pitfall is that kind of thinking - if you think of it as removing nulls and you're not mindful, you might be deleting things from the list you don't want to be deleting.

Do you really though, or are you being a bit hyperbolic? It's really not that complicated or arbitrary. If you find yourself hitting idiosyncrasies so often you've got the docs open you might just be doing it wrong. There's also some learning to do for any language, no language is so intuitive that you know it without any effort or learning.

All the above said, do enough real work in any language and you'll find cases where the idioms of the language don't map to your work.

PHP isn’t consistent with itself and has abstraction leaks for things that it shouldn’t. PHP does not bring me joy.

Of course I’m speaking succintly above. It’s not that bad, but it’s not that much better either. I’m not going to stockholm myself into using a language just because it’s “mature” if I don’t have to. I may have that relationship with JavaScript but at least in that case resistance is somewhat futile and there are practical benefits to be had.

I don't know any language that this statement isn't true about unless either:

(a) you're a true, deep expert who uses the language all day every day

(b) the docs are so poor it's not even worth having them open

Go might be a contender save for a couple weird features. JS might be with a few ground rules and/or enough tooling.

I’m also willing to grant implicitly that there are tradeoffs here. Languages with small standard libraries usually have big community libraries and vice/versa.

JS isn't directly comparable due to the very delineated nature of ECMA -vs- DOM/NodeJS APIs - ECMA is pretty easy to internalise but you'd be hard pressed to get by without MDN DOM or NodeJS core API docs open (unless as you say you're abstracting them with community libs as you say).

I've only used Go sparingly - I heavily relied on docs, but yeah it may have a shallow learning curve. It's certainly much saner than Python (which seems to be the other language used in my "space" for e.g. ad hoc ops tooling, etc.)

Get a better IDE. Visiting docs for checking return values should be a thing in the past.

My approach (very similar than when I write C or raw JS) is to use a few "cleanup" APIs or libs that hide the nasty stuff (string handling / array iteration / SQL building), because I know I don't want to deal with all the footguns. There were rarely is a performance argument that would need me to do otherwise.

I use PHP daily at work, haven't had to check the docs for quite a while

Exactly. You get it 100%. Come work for me!

just gonna leave this comment here to reply to the person whose blog I've followed years before Browserling was created.

Why, thank you!

In general, how could one know that something has no unknown unknowns? By definition, one wouldn't know.

That's what makes the statement "no 'unknown unknowns'" a bit ridiculous though. How can you possibly assert that there are absolutely NO 'unknown unknowns'? You can never rule them out, and at best can only suspect there's a possibility either way, that they do or do not exist. You can never actually know with certainty.

You can have a statistic approach, and that's what the OP is referring to. If you find out about an unknown unknown frequently, they are out there. If you go years without hitting one, they are (probably) absent.

Schrödinger’s Cat?

I suppose the programming equivalent is something that randomly results in a line being printed to the console.

Schrödinger's PHP.

Being a PHP programmer for 14 years never found an example of that.

Any examples?

But genuine question -- what other languages are as simultaneously as useful AND predictable?

Ruby, Python, C#, Java, and JavaScript are all are more predictable and just as useful. Go, Elixir, Clojure, and probably others are more predictable while being less "useful" only in the sense that they may have less convenient deployments or less mature web libraries.

I've used Python, C#, Java, JavaScript and PHP, and in my experience Python is the most unpredictable of these languages. Just to name a few: - mutable default arguments - late binding closures - typings that are purely documentation instead of being enforced

Labeling these things as "gotchas" doesn't make them predictable imo.

Python less predictable than PHP? In what world? In PHP standard library functions silently take a null instead of a string, even though they are string handling functions, hiding that mistake for the user of the language, until a later point in time, when the context has been lost and one needs to do silly debugging, until one finds the place where the null first was handled, while it should have raised an error. Such is the silly character of PHP standard library. Many functions also have multiple return types, which makes it difficult to simply use the result of one as input to another.

If predictability means to predict, that standard library will behave nonsensically, then yes, PHP has the one high predictability.

> silently take a null instead of a string

Oh, so you _haven't_ used any of the recent versions of PHP, then. You're just talking shit with no actual recent experience. Gotcha. Well, thanks for your input.

Look what I got here for you:

    docker run -it php:8.0 bash
    # php -a
    Interactive shell

    substr("abcdef", 3);
    // no result

-- Ah right, PHP does things differently than other almost every other language that has a REPL and I have to echo a value, which was just returned, even on the REPL ...

    php > echo substr("", 3);

-- Silently hiding the error. Idiocy.

    php > echo substr(null, 3);

-- Silently hiding the error. Idiocy.

    php > echo substr("abcdef", 3);
    def

Who is shit talking now? Are you suggesting, that all this is normal and OK? Nothing is fixed. It's still badly designed and probably will remain shitty like that, until PHP programmers finally realize, that this needs to be properly fixed.

EDIT: Of course the docs also do not mention this to happen at all and tell you, that the first argument must be a string. So I guess that means, that in PHP terms, null is a string. Great for type safety!

These problems were fixed in PHP 8.0 and 8.1

https://wiki.php.net/rfc/engine_warnings

https://wiki.php.net/rfc/deprecate_null_to_scalar_internal_a...

Go is more difficult to deploy than php? php.ini files and php extension installations to get to production is what I remember

No, I was thinking 'less mature web libraries' for Go. It's hard to talk about groups of languages in broad strokes when there are various tradeoffs and each language has its own strengths and weaknesses, and I painted two possible weaknesses broadly across several languages that don't strictly apply to all of them.

I am starting to find PHP bearable as soon as they are starting to follow Python language and precepts (like libs for humans, code readability instead of shorthands,...)

Python covers many of the same use cases and is much more consistent/predictable. TCL if you want to go back a bit further.

I've never experienced the same kind of out-of-the-box problems with PHP as I have Python. I seem to suffer constantly from python/python3, pip inconsistencies and stuff just breaking constantly.

Python build/package management tooling is a joke, but Python the language is very consistent and usable.

Ooh, now that's a good question.

Which is more important really? I genuinely don't know the answer to this.

I don't think it's an either/or; more like both language and tooling can eat into your annoyance budget and you look for the combination that has the lowest overall cost.

With Python one never knows when a particular feature code depends on will be removed. With PHP code written 15 years ago still works.

> With PHP code written 15 years ago still works.

If you never upgrade, sure. PHP 7 and each minor version in it have deprecated and removed plenty of stuff that was legal in 5.6. PHP 8 is on track to do more of the same. I think the backwards incompatible changes are pretty much all good for the language, but claiming backwards compatibility in PHP is completely wrong.

If you aren't on PHP 8, you aren't supported, and if you're on anything earlier than 7.4, you aren't getting security releases. And the new versions released yearly all have breaking changes, and get three years of security support. It's not 2015 anymore.

What features have been removed from Python?

Besides the obvious 2 to 3 transition, cpython has obsoleted or renamed stdlib modules several times between 3.x versions. For example, the collections.abc change causes several common Linux bits to break if you change the system default to 3.8.

Which is a double edged sword. How many ways can one escape a string, and for how many of them will you find a stack overflow comment from a decade ago saying are the secure option to use?

ruby...

To which most developers say, oh well, because they'll never encounter them.

Like what? Come on, if it's that common you must have at least one example.

It literally doesn’t matter. You fix the bug, deploy, and move on on.

Perhaps those people are stuck with PHP 5.

For example?

What are you referring to?

Examples?