Add an "About the manual" page talking about how examples can('t) be run within WASM, and then link to it

[damianwadley]

Running the code examples on php.net is great but people don't know it's imperfect: it's done through WASM which is limited in what it can do, PHP-on-WASM is even more limited in what it supports, and people running examples will frequently find out about these limitations without knowing. As evidenced by the handful of bug reports here saying that there's a problem with an example when actually there isn't - bug reports that will continue on forever unless something is done.

The flaws are unavoidable, so the solution should be to make sure people are aware of them.

While I was thinking about this, I came up with 3 solutions that aren't great:

1. Add a little (?) icon or Help button that gives a tooltip/popup/collapsable info box. The JS setup could do this, but then there's a problem of trying to provide translations.
2. Add some error detection logic in the JS runner, as in something to look for "Call to undefined function" messages and the like, that then presents Clippy-style help. The (second) problem with this is the lack of translation support.
3. Add metadata to examples about their requirements, eg. if they require specific extensions/classes/functions/etc. This is... hard.

While I like that third option most, it would take time and effort across multiple repositories, and after that still require the work with the examples themselves - many, many, many of them - to add the appropriate metadata. There's also minor problems like people having to remember to annotate examples, but perhaps some of that could be alleviated within the doc system.
All told, my first goal is to get something out there sooner rather than later, which means one of the first two options. Except they have the translation problems. I consider translation support to be important too, which means the informational message should be handled somewhere within doc-* and not web-php itself. And the best way of doing that would be to create a page that explains the WASM stuff.

Part 1: create such a page.

Here are some important aspects about running the examples that I think people should know about:

• It happens in the browser through WASM and not on the server.
• WASM is 32-bit, which won't be an issue very often but will happen when dealing with integers around the PHP_INT_MIN/MAX bounds - which will be much lower than developers are used to these days. This will most notably affect date/time functions working with Unix timestamps.
• WASM is heavily sandboxed: no filesystem or network access, so the examples cannot do even simple PHP operations like read files or make HTTP requests.
• Only some of the basic "core" PHP extensions are available - no cURL or Intl or PDO.
• Some features that depend on INI settings and happen before execution (eg. errors and error_reporting, declare encoding and zend.multibyte) may not be possible.
• The WASM build is manually maintained, meaning there's only one version available and it won't be the latest one. (current version is 8.4.0-dev) Ideally this would be automated to use the latest version but that's a separate problem.

That information should be written in a page somewhere that people can read. Remember that the page would (presumably) be included in the downloads so specifically mentioning that WASM support is for the online manual would be good.

With a page available, people need to know to read it. And if anything, people on php.net don't know what they need to read. So the page needs to be made known, and the simplest way of doing that would be to include a link next to each example.

Part 2: add a link by examples that goes to the new doc page.

It should be sufficient to make the link itself brief - like a (?) icon, or an "About" or "Help" label. I'd put it next to the "Run code" button so it's hard to miss.

I think the best place to implement that would be within web-php's JS runner. That couples it directly to the WASM feature itself, and makes placing the link next to the button much easier. And while a link label wouldn't be translated, a simple word like "About" or "Help" should be fine (and an icon even better). A PR/Issue can be made over there when the page is available to link to.

The other option would be to embed it into the example template, but while that can mean a translated label, it also means no coupling (which is occasionally a good thing), and coordinating the button + link is harder, and that something should be done to make sure it didn't get included in the downloads where it wouldn't make sense.

[Girgias]

I think this is a good idea, I guess having this as an appendix makes the most sense?

[jezmck]

From a UX perspective, any button which might not work is really bad.
Surely it's best to remove all buttons which it's known will show an error?
Or better, disable it and show a message explaining why it can't work.

[damianwadley]

In other words, my solution 3, which I rejected because of the time and effort required to make it happen. In the future, sure, it would be the most comprehensive and thorough solution (at least it could be if done in a way that people wouldn't have to constantly remember when writing doc pages), but we need something sooner than that.