Enable More Examples for WASM #4799
Description
Recently, we have enabled running examples with WASM in the documentation. But it is only enabled for a few chapters and books, such as:
The reason for this is that many examples do not run, due to either extensions not being available, examples not being self-contained, or working, or not producing any output.
Therefore, the WASM runner for examples is only enabled for a specific book or chapter when the annotations="interactive" attribute is set on these books and chapters.
In some cases, certain examples inside each section need to be disabled because they have code without output, or they're not full examples. You can do this by setting the annotations="non-interactive" element on an example.
All examples need to be checked before we can enable WASM for each section (book or chapter), and below you will find a list of all the sections in the manual that have some chance of success.
I would recommend that each section is looked at separately, but also in its entirety. Please don't add annotations="interactive" to anything which you haven't checked to work. If a function or page does not have an example, consider adding one!
The easiest way to do this, is by following the following procedure:
- Check out the php web source code:
git clone https://github.com/php/web-php.git - Go to the manual directory, and remove the
endirectory (it contains sample documentation online):cd php-web/manual && rm -rf en && cd - - Create a symlink to the location where you build the location:
ln -s /tmp/docs/php-web/ en - Use the build in webserver to serve the php website:
cd php-web && php -S localhost:8888 .router.php - Build the documentation as normal, and make sure to select the right output directory (from the documentation root directory):
cd ~/dev/php/phpdoc && php doc-base/configure.php && php -dmemory_limit=2G phd/render.php --docbook doc-base/.manual.xml --output=/tmp/docs --package PHP --format php
Then navigate your browser to the "head" of the section to work on (for example http://localhost:8082/manual/en/book.calendar.php), and then on every page, check each example whether it runs, and produces the right output. If it doesn't, try to fix the example(s), and then run step 5 again from above. I navigate between each page by using the navigation in the top right so not to miss anything.
Not all of these extensions have been compiled into our WASM build, but it is possible to extend this — add an issue at https://github.com/derickr/php-wasm-builder/issues to do so.
Besides the extensions, the WASM runner also have a few files in the filesystem that you can read and write to. You can find the current list at https://github.com/derickr/php-wasm-builder/tree/main/examples, and they are mapped to examples. I.e., https://github.com/derickr/php-wasm-builder/blob/main/examples/book-docbook.xml maps to examples/book-docbook.xml (See it used in http://localhost:8082/manual/en/domattr.isid.php#refsect1-domattr.isid-examples, but also in http://localhost:8082/manual/en/simplexml.examples-basic.php#example-5860). If you need more files, you can submit a PR at https://github.com/derickr/php-wasm-builder/pulls again.
If you have questions, please reach out to us on Discord. Feel free to add a comment behind each section in this list as well, with your handle, or other notes. You can also convert a task to a sub-issue, which will then also allow you to claim a section by assigning that one to yourself.
Now, the (massive) list — not all sections might have examples, nor an extension that we (currently) support:
- chapters/intro
- chapters/tutorial
- features/commandline
- features/connection-handling
- features/cookies
- features/dtrace
- features/file-upload
- features/gc
- features/http-auth
- features/persistent-connections
- features/remote-files
- features/sessions
- language/attributes
- language/basic-syntax
- language/constants
- language/control-structures
- language/enumerations
- language/errors
- language/exceptions
- language/expressions
- language/fibers
- language/functions
- language/generators
- language/namespaces
- language/oop5
- language/operators
- language/references
- language/types
- language/variables
- reference/array
- reference/bc
- reference/bzip2
- reference/calendar
- reference/classobj
- reference/ctype
- reference/datetime
- reference/dbase
- reference/dir
- reference/dom
- reference/ds
- reference/enchant
- reference/errorfunc
- reference/event
- reference/exif
- reference/fileinfo
- reference/filesystem
- reference/filter
- reference/ftp
- reference/gmp
- reference/hash
- reference/hrtime
- reference/iconv
- reference/image
- reference/imagick (not sure if we can make this work)
- reference/info
- reference/json
- reference/libxml
- reference/mail
- reference/math
- reference/mbstring
- reference/memcache
- reference/misc
- reference/network
- reference/oauth
- reference/opcache
- reference/openssl
- reference/password
- reference/pcre/book
- reference/pcre/pattern.syntax
- reference/phar
- reference/posix
- reference/ps
- reference/pthreads
- reference/recode
- reference/reflection
- reference/reflection/extending
- reference/rpminfo
- reference/session
- reference/session/upload-progress
- reference/simplexml
- reference/soap
- reference/sockets
- reference/sodium
- reference/spl
- reference/sqlite3
- reference/stats
- reference/stream
- reference/strings
- reference/tidy
- reference/tokenizer
- reference/url
- reference/var
- reference/wddx
- reference/xattr
- reference/xdiff
- reference/xlswriter
- reference/xml
- reference/xmldiff
- reference/xmlreader
- reference/xmlrpc
- reference/xmlwriter
- reference/xpass
- reference/xsl
- reference/yaf
- reference/yaml
- reference/yar
- reference/zip
- reference/zlib
- security/apache
- security/cgi-bin
- security/current
- security/database
- security/errors
- security/filesystem
- security/general
- security/hiding
- security/intro
- security/sessions
- security/variables