[Docs] Updating run cli demos

[fellyph]

Motivation for the change, related issues

Updating the runCLI demos to show other ways of working with the method, applying for tests. Including more examples of the new flags. The change also included a description to improve the page SEO and apply some recommendations of the WordPress Docs handbook.

New demos:

• Setting a custom site URL
• Multiple mounts
• Symlink support for monorepos
• Testing plugins with specific PHP versions
• Mode selection (Blueprint v2)
• Skip WordPress and SQLite setup
• Error handling
• Following symlinks programmatically

Portuguese and Spanish versions are also included.

[adamziel]

Really cool, thank you! I've left a few comments, nothing major.

[fellyph]

@adamziel I have removed the blueprints v2 examples temporarily and added the suggested changes

[adamziel]

Hm this paragraph reads weird. Are we selling the user on mounting project files? It's also unclear why we'd want to skip the boot process (which we're not skipping, Playground still boots and will try to install WordPress) and how exactly does it help connect Playground with WP-CLI. Let's take this opportunity to clarify it and, e.g.:

When you have a local WordPress site, you can run it in Playground CLI as well. Here's one way to do it:

npx @wp-playground/cli@latest server \
     --mount-dir-before-install ./wordpress-path-on-host /wordpress/ \
     --wordpress-install-mode=do-not-attempt-installing

To unpack it, that command mounted the entire WordPress site you already had on your disk using the --mount-dir-before-install flag. That mount happened before Playground had a chance to download another WordPress version and unzip it in /wordpress. Then, we've told Playground CLI to skip running the WordPress installer. That site was already installed, so why would we?

With this workflow, you can store your WordPress site directly in the filesystem, retain it across multiple Playground CLI executions, and use the usual WordPress tools with it, e.g. WP-CLI.

You can also use the --mount-dir-before-install flag to populate a local directory with a newly created WordPress site:

npx @wp-playground/cli@latest server \
     --mount-dir-before-install ./wordpress-path-on-host /wordpress/

Since we did not skip the installer, Playground CLI runs the site setup as usual, only this time the /wordpress directory is connected to your local directory. At the end of the command, the new site files are stored in ./wordpress-path-on-host in your local filesystem! To run that site again, use the --wordpress-install-mode flag discussed above.

[adamziel]

This sounds scary! Let's explain what kind of security risks are we facing here – it's not that bad if you trust the site.

[fellyph]

Can symlink points to sensitive files elsewhere on your system (like /etc/passwd or ~/.ssh/), those files could become accessible to the WordPress site running in Playground and expose to malicious code?

[adamziel]

Yeah, that's exactly the risk. If you're running an untrusted Blueprint, that's a problem. But if you're just working on a local site and you trust the code, it's not a big deal. I'd just say that part out loud in the doc

[adamziel]

The reader probably got the idea by now and understands they can just pass the same flags in a shell command and the runCLI() function. What do you think about skipping a few of these option-specific examples? They inflate the document and IMHO don't add that much value. If something can be explained with more words or less words, less words is always more convenient – it's less work for the user.

[fellyph]

Can those code snippets be a post on the blog? I think we need to have a space for more code examples.

[fellyph]

Another alternative will be create a dedicated page for runCLI

[adamziel]

Blog post sounds good 👍 Or maybe a sub-page just for these examples? So just like you've proposed.