From 33e00ebfb31a86d9898095d64366d481f81aa38c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Sat, 2 May 2026 03:08:21 +0200 Subject: [PATCH] docs: link READMEs to the runnable docs site Now that PR #244 is merged and GitHub Pages is enabled, add a banner pointing readers to https://wordpress.github.io/php-toolkit/ from the top of every component README, the root README, and the create-wp-site example. Component banners deep-link to the matching reference page so readers land directly on the live, executable snippets. The root README is also restructured around the docs site: the component list becomes a table where each row links to both the component README and its live reference page, and a callout makes the docs site the recommended source for code samples (verified in CI by the existing snippet-tests workflow). --- README.md | 136 ++++++++++---------- components/BlockParser/README.md | 5 + components/Blueprints/README.md | 5 + components/ByteStream/README.md | 5 + components/CLI/README.md | 5 + components/CORSProxy/README.md | 5 + components/DataLiberation/README.md | 5 + components/Encoding/README.md | 5 + components/Filesystem/README.md | 5 + components/Git/README.md | 5 + components/HTML/README.md | 5 + components/HttpClient/README.md | 5 + components/HttpServer/README.md | 5 + components/Markdown/README.md | 5 + components/Merge/README.md | 5 + components/Polyfill/README.md | 5 + components/ToolkitCodingStandards/README.md | 5 + components/XML/README.md | 5 + components/Zip/README.md | 5 + examples/create-wp-site/README.md | 4 + 20 files changed, 162 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 959f69ee5..12d123097 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,81 @@ ## PHP Toolkit -Standalone PHP libraries for use in WordPress plugins and standalone PHP projects: - -- XMLProcessor – stream-parse XML files on any PHP installation (no libxml2 required). -- Git – a pure PHP implementation of Git client and server. -- HttpClient – a streaming, non-blocking, concurrent HTTP client library with no curl dependency. -- Zip – stream-parse and stream-write ZIP files with no libzip dependency. -- Data Liberation – generic streaming data importers to WordPress. Supports WXR, zipped markdown, remote git repos, rewriting URLs, and more. -- ByteStream – composable byte streaming utilities – readers, writers, filters. -- Markdown – convert between markdown and block markup with no dependencies. -- Filesystem – single API for working with local files, Git, Google drive, memory, etc. - -This fork consolidates a few earlier projects and explorations into a single composer package. + +> **📚 Live, runnable docs:** **** +> Every component has a reference page with examples that execute in WordPress Playground — edit code in your browser, click *Run*, see real output. There's also a short [learning path](https://wordpress.github.io/php-toolkit/learn/). + + +Standalone, dependency-free PHP libraries for use in WordPress plugins and standalone PHP projects. + +### Components + +| Component | What it does | Live docs | +| --- | --- | --- | +| [HTML](components/HTML/README.md) | Stream-modify real-world HTML without `libxml2` (mirrors `WP_HTML_Tag_Processor`/`WP_HTML_Processor`). | [reference/html](https://wordpress.github.io/php-toolkit/reference/html.html) | +| [XML](components/XML/README.md) | Stream-parse XML files on any PHP installation — no `libxml2` required. | [reference/xml](https://wordpress.github.io/php-toolkit/reference/xml.html) | +| [Zip](components/Zip/README.md) | Stream-read and stream-write ZIP archives with no `libzip` dependency. | [reference/zip](https://wordpress.github.io/php-toolkit/reference/zip.html) | +| [Markdown](components/Markdown/README.md) | Convert between Markdown and WordPress block markup. | [reference/markdown](https://wordpress.github.io/php-toolkit/reference/markdown.html) | +| [BlockParser](components/BlockParser/README.md) | Parse and serialize WordPress block markup. | [reference/blockparser](https://wordpress.github.io/php-toolkit/reference/blockparser.html) | +| [HttpClient](components/HttpClient/README.md) | Streaming, non-blocking, concurrent HTTP client — no `curl` extension. | [reference/httpclient](https://wordpress.github.io/php-toolkit/reference/httpclient.html) | +| [HttpServer](components/HttpServer/README.md) | Minimal pure-PHP HTTP server primitives. | [reference/httpserver](https://wordpress.github.io/php-toolkit/reference/httpserver.html) | +| [CORSProxy](components/CORSProxy/README.md) | A small CORS proxy you can drop in front of arbitrary HTTP traffic. | [reference/corsproxy](https://wordpress.github.io/php-toolkit/reference/corsproxy.html) | +| [Git](components/Git/README.md) | Pure-PHP Git client and server. | [reference/git](https://wordpress.github.io/php-toolkit/reference/git.html) | +| [Filesystem](components/Filesystem/README.md) | Single API across local files, ZIP, Git, Google Drive, in-memory, etc. | [reference/filesystem](https://wordpress.github.io/php-toolkit/reference/filesystem.html) | +| [ByteStream](components/ByteStream/README.md) | Composable byte streaming utilities — readers, writers, filters. | [reference/bytestream](https://wordpress.github.io/php-toolkit/reference/bytestream.html) | +| [DataLiberation](components/DataLiberation/README.md) | Streaming data importers for WordPress (WXR, zipped Markdown, remote git, URL rewriting…). | [reference/dataliberation](https://wordpress.github.io/php-toolkit/reference/dataliberation.html) | +| [Encoding](components/Encoding/README.md) | Encoding-detection and conversion helpers. | [reference/encoding](https://wordpress.github.io/php-toolkit/reference/encoding.html) | +| [Merge](components/Merge/README.md) | Three-way text and structural merge primitives. | [reference/merge](https://wordpress.github.io/php-toolkit/reference/merge.html) | +| [Polyfill](components/Polyfill/README.md) | PHP 8.0 string functions and minimal WordPress stubs (hooks, escaping, `WP_Error`). | [reference/polyfill](https://wordpress.github.io/php-toolkit/reference/polyfill.html) | +| [CLI](components/CLI/README.md) | Helpers for building friendly PHP command-line tools. | [reference/cli](https://wordpress.github.io/php-toolkit/reference/cli.html) | +| [Blueprints](components/Blueprints/README.md) | Reproducible WordPress environment setup (the runtime behind `blueprints.phar`). | [reference/blueprints](https://wordpress.github.io/php-toolkit/reference/blueprints.html) | +| [ToolkitCodingStandards](components/ToolkitCodingStandards/README.md) | Shared PHPCS ruleset used across the toolkit. | [reference/coding-standards](https://wordpress.github.io/php-toolkit/reference/coding-standards.html) | + +> **Looking for code samples?** Prefer the [live docs](https://wordpress.github.io/php-toolkit/) — every snippet is executable in-browser and is verified against the latest `trunk` in CI. Component README files contain the same code, but the docs site is where it ships first. ### Using the Blueprints v2 runner -The Blueprints v2 runner is an all-php CLI tool that runs Blueprints v1 and v2. To use it, download [blueprints.phar from the latest release](https://github.com/WordPress/php-toolkit/releases) and run it: +The Blueprints v2 runner is an all-PHP CLI tool that runs Blueprints v1 and v2. Download [blueprints.phar from the latest release](https://github.com/WordPress/php-toolkit/releases) and run it: ```sh php blueprints.phar ``` -From there, follow the help message for required arguments and options. - -If you want to use Blueprints as a library, you absolutely can. It is designed to be reusable, -compatible with web and CLI environments on PHP 7.2+. There's not much technical documentation -at this point but you can refer to the [blueprints.php file](https://github.com/WordPress/php-toolkit/blob/219dc4e846af270a5009e523244d0ec23baaa32a/components/Blueprints/bin/blueprint.php#L226) to see -how the runner is implemented. +From there, follow the help message for required arguments and options. If you want to use Blueprints as a library, you absolutely can — see the [Blueprints reference page](https://wordpress.github.io/php-toolkit/reference/blueprints.html) for runnable examples. ### Using the components -The individual components are now distributed via Composer at [https://packagist.org/packages/wp-php-toolkit](https://packagist.org/packages/wp-php-toolkit). You can install specific components you need rather than the entire toolkit. - -To install a specific component, use composer: +Each component is independently published on Packagist under [`wp-php-toolkit/*`](https://packagist.org/packages/wp-php-toolkit/). Install only the pieces you need: ```bash composer require wp-php-toolkit/http-client composer require wp-php-toolkit/data-liberation composer require wp-php-toolkit/git -# ... and so on for other components +# ... and so on ``` #### PHAR distribution -For convenience, a standalone Blueprints runner and other tools from this repository are shipped as phar files available in the [GitHub releases](https://github.com/WordPress/php-toolkit/releases). +For convenience, a standalone Blueprints runner and other tools from this repository ship as PHAR files in the [GitHub releases](https://github.com/WordPress/php-toolkit/releases). ### Design goals -- Build re-entrant data tools that can start, stop, resume, tolerate errors, accept alternative media files, posts etc. from the user. -- WordPress-first – Everything is built in PHP using WordPress coding standards. The divergences are strategic and minimal, such as the use of namespaces. -- Compatibility – Support for major WordPress versions, PHP version (7.2+), and Playground runtime (web, CLI, browser extension, desktop app, CI etc.). -- Dependency-free – No PHP extensions are required and only minimal Composer dependencies are allowed when absolutely necessary. -- Simple – The architectural role model is [WP_HTML_Processor](https://developer.wordpress.org/reference/classes/wp_html_processor/) – a **single class** that can parse nearly all HTML. There's no "Node", "Element", "Attribute" classes etc. Let's aim for the same here. Some OOP patterns are used when useful, but we're explicitly avoiding ideas like AbstractSingletonFactoryProxy. -- Extensibility – Playground should be able to benefit from, say, WASM markdown parser even if core WordPress cannot. -- Reusability – Each library should be framework-agnostic and usable outside of WordPress. +- **Re-entrant data tools** that can start, stop, resume, tolerate errors, and accept alternative media files, posts, etc., from the user. +- **WordPress-first** — Everything is built in PHP using WordPress coding standards. Divergences are strategic and minimal (e.g. namespaces). +- **Compatibility** — Major WordPress versions, PHP 7.2+, and Playground runtimes (web, CLI, browser extension, desktop app, CI, etc.). +- **Dependency-free** — No PHP extensions required and only minimal Composer dependencies, allowed only when absolutely necessary. +- **Simple** — The architectural role model is [`WP_HTML_Processor`](https://developer.wordpress.org/reference/classes/wp_html_processor/): a single class that does one thing well. No `AbstractSingletonFactoryProxy`. +- **Extensibility** — Playground should be able to benefit from, say, a WASM Markdown parser even if WordPress core cannot. +- **Reusability** — Each library is framework-agnostic and usable outside WordPress. ### Development #### Dev Container -A [Dev Container](https://containers.dev/) spec is included in `.devcontainer/`. -It provides PHP 8.1 with all the required extensions, Composer, and editor -tooling pre-configured. Works with VS Code ("Reopen in Container"), GitHub -Codespaces, or `devcontainer up --workspace-folder .` from the CLI. +A [Dev Container](https://containers.dev/) spec is included in `.devcontainer/`. It provides PHP 8.1 with all required extensions, Composer, and editor tooling pre-configured. Works with VS Code ("Reopen in Container"), GitHub Codespaces, or `devcontainer up --workspace-folder .` from the CLI. #### Docker sandbox -For running tests and lints in an isolated container without a full dev -environment, use the Docker Compose sandbox: +For running tests and lints in an isolated container without a full dev environment, use the Docker Compose sandbox: ```sh # Build once @@ -86,13 +94,11 @@ docker compose run --rm sandbox php my-script.php docker compose run --rm sandbox vendor/bin/phpcs -d memory_limit=1G . ``` -The sandbox has no network access, a read-only root filesystem, and all Linux -capabilities dropped — the only writable areas are the project mount and `/tmp`. +The sandbox has no network access, a read-only root filesystem, and all Linux capabilities dropped — the only writable areas are the project mount and `/tmp`. #### Without Docker -The test suite works directly on the host too — no database, no web server, -no external services needed. You just need PHP 7.2+ with `json` and `mbstring`. +The test suite works directly on the host too — no database, no web server, no external services needed. You just need PHP 7.2+ with `json` and `mbstring`. #### Testing @@ -112,17 +118,27 @@ To fix the linting errors, run: composer lint-fix ``` +#### Building the docs site + +The docs site under `docs/` is generated. To rebuild and preview locally: + +```sh +python3 bin/build-docs.py +python3 bin/build-reference.py +python3 bin/serve-docs.py # opens http://localhost:8787 +``` + +Snippets used in the site live in `bin/_docs_components.py`. They run in CI on every PR (see `.github/workflows/snippet-tests.yml`) and in WordPress Playground from the live site. + #### Composer -The root composer.json file is an amalgamation of composer.base.json all -component composer.json files. To regenerate it, run: +The root `composer.json` is generated from `composer.base.json` and the per-component `composer.json` files. To regenerate after changing a component's `composer.json`: ```sh bin/regenerate_composer.json.php ``` -This will merge all the package-specific dependencies and the autoload rules into -the root composer.json file. +This merges all package-specific dependencies and autoload rules into the root `composer.json`. ### Windows compatibility @@ -130,24 +146,15 @@ Windows compatibility is achieved on a few different fronts: #### Newlines -This repository comes with a `.gitattributes` file to ensure that the unit test -files and fixtures are normalized to `\n` on checkout. It's important, because -Windows uses `\r\n` for newlines in text files. Unix-based systems use `\n`. -Without the `.gitattributes`, git on Windows would replace all the `\n` with `\r\n` -on checkout. +This repository comes with a `.gitattributes` file to ensure that the unit test files and fixtures are normalized to `\n` on checkout. It's important, because Windows uses `\r\n` for newlines in text files. Unix-based systems use `\n`. Without the `.gitattributes`, git on Windows would replace all the `\n` with `\r\n` on checkout. -The strings produced by the library uses `\n` for newlines where it can make -that choice. For example, the `WXRWriter` class will separate XML tags with -`\n` newlines to make sure the generated XML is consistent across platforms. +The strings produced by the library use `\n` for newlines where it can make that choice. For example, the `WXRWriter` class will separate XML tags with `\n` newlines to make sure the generated XML is consistent across platforms. #### Paths -The `Filesystem` components makes a point of using Unix-style forward slashes -as directory separators, even on Windows. +The `Filesystem` component makes a point of using Unix-style forward slashes as directory separators, even on Windows. -As a library consumer, ensure all the local paths you pass to the library are -using Unix-style forward slashes as directory separators. A simple str_replace -will do the trick: +As a library consumer, ensure all the local paths you pass to the library are using Unix-style forward slashes as directory separators. A simple `str_replace` will do the trick: ```php if (DIRECTORY_SEPARATOR === '\\') { @@ -155,23 +162,16 @@ if (DIRECTORY_SEPARATOR === '\\') { } ``` -The reason for using Unix-style forward slashes is care for data integrity. -Windows understands both forward slashes and backslashes, so the replacement -operation is safe there. On Unix, however, a backslash can be used as a part -of a filename so it cannot be safely translated. +The reason for using Unix-style forward slashes is care for data integrity. Windows understands both forward slashes and backslashes, so the replacement operation is safe there. On Unix, however, a backslash can be used as part of a filename so it cannot be safely translated. -Importantly, do not just run this str_replace() on every possible path. -`C:\my-dir\my-file.txt` is both, a valid Windows absolute path and a valid Unix -filename and a relative path. Furthermore, `Filesystem` supports more filesystems -than just local disk. +Importantly, do not just run this `str_replace()` on every possible path. `C:\my-dir\my-file.txt` is both a valid Windows absolute path and a valid Unix filename / relative path. Furthermore, `Filesystem` supports more filesystems than just local disk. Anytime you're handling paths, consider: - Which filesystem is this path related to? Local? Remote? Git? - Which OS are you on? Windows? Unix? -If the answers are "local" and "Windows", you may need to apply the `str_replace()` -slash normalization. Otherwise, just keep the path as it is. +If the answers are "local" and "Windows", you may need to apply the `str_replace()` slash normalization. Otherwise, just keep the path as it is. The takeaway from this section is: **paths are difficult**. diff --git a/components/BlockParser/README.md b/components/BlockParser/README.md index fa0d7b2b6..8c7fb0119 100644 --- a/components/BlockParser/README.md +++ b/components/BlockParser/README.md @@ -1,5 +1,10 @@ # BlockParser + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/blockparser.html](https://wordpress.github.io/php-toolkit/reference/blockparser.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + ## Why this exists WordPress stores post content as annotated HTML. Instead of inventing a separate file format, it embeds block boundaries directly inside HTML comments: diff --git a/components/Blueprints/README.md b/components/Blueprints/README.md index 23f4519eb..6a4250b5d 100644 --- a/components/Blueprints/README.md +++ b/components/Blueprints/README.md @@ -1,5 +1,10 @@ # Blueprints + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/blueprints.html](https://wordpress.github.io/php-toolkit/reference/blueprints.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + Declarative WordPress site provisioning. Define a site's desired state as a JSON blueprint -- which plugins to install, which options to set, which content to import -- and let the runner execute it. Blueprints can create a new WordPress site from scratch or modify an existing one, making them useful for development environments, demo sites, automated testing, and reproducible WordPress setups. ## Installation diff --git a/components/ByteStream/README.md b/components/ByteStream/README.md index 30809cef4..b64ca757b 100644 --- a/components/ByteStream/README.md +++ b/components/ByteStream/README.md @@ -1,5 +1,10 @@ # ByteStream + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/bytestream.html](https://wordpress.github.io/php-toolkit/reference/bytestream.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + Composable streaming primitives for reading, writing, and transforming byte data in pure PHP. ByteStream provides a pull-based model where you request bytes from a source, peek at or consume them, and optionally transform them through filters like compression or checksums -- all without loading entire files into memory. ## Installation diff --git a/components/CLI/README.md b/components/CLI/README.md index a9a1047fc..b66cc45e8 100644 --- a/components/CLI/README.md +++ b/components/CLI/README.md @@ -1,5 +1,10 @@ # CLI + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/cli.html](https://wordpress.github.io/php-toolkit/reference/cli.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + A POSIX-style command-line argument parser for PHP. It handles long options (`--verbose`), short options (`-v`), bundled short options (`-abc`), inline values (`--port=8080`, `-p=8080`), and positional arguments -- all in a single static method call with no external dependencies. ## Installation diff --git a/components/CORSProxy/README.md b/components/CORSProxy/README.md index d91e033cd..3303ee60b 100644 --- a/components/CORSProxy/README.md +++ b/components/CORSProxy/README.md @@ -1,5 +1,10 @@ # CORSProxy + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/corsproxy.html](https://wordpress.github.io/php-toolkit/reference/corsproxy.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + A PHP CORS proxy that lets browser-based JavaScript make cross-origin requests to external services. Built for WordPress Playground to bridge `fetch()` calls to git servers and other APIs that don't set CORS headers. The proxy streams data bidirectionally, blocks requests to private IP ranges, filters sensitive headers, and enforces size limits -- all without external dependencies. ## Installation diff --git a/components/DataLiberation/README.md b/components/DataLiberation/README.md index e260a2fec..26c037d37 100644 --- a/components/DataLiberation/README.md +++ b/components/DataLiberation/README.md @@ -1,5 +1,10 @@ # DataLiberation + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/dataliberation.html](https://wordpress.github.io/php-toolkit/reference/dataliberation.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + Streaming data import and export for WordPress. Reads and writes WordPress content in multiple formats -- WXR (WordPress eXtended RSS), SQL dumps, block markup, and more -- without loading everything into memory. Designed for migrating content between WordPress sites, converting between formats, and processing large exports that would otherwise exhaust PHP's memory limits. ## Installation diff --git a/components/Encoding/README.md b/components/Encoding/README.md index add937614..f2310375e 100644 --- a/components/Encoding/README.md +++ b/components/Encoding/README.md @@ -1,5 +1,10 @@ # Encoding + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/encoding.html](https://wordpress.github.io/php-toolkit/reference/encoding.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + Pure PHP utilities for UTF-8 validation, scrubbing, and conversion. This component detects invalid byte sequences, replaces them with the Unicode Replacement Character using the maximal subpart algorithm, and provides low-level tools for working with Unicode code points -- all without requiring the `mbstring` extension. When `mbstring` is available, the library delegates to it for better performance. ## Installation diff --git a/components/Filesystem/README.md b/components/Filesystem/README.md index 153d0e525..dcdb2add7 100644 --- a/components/Filesystem/README.md +++ b/components/Filesystem/README.md @@ -1,5 +1,10 @@ # Filesystem + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/filesystem.html](https://wordpress.github.io/php-toolkit/reference/filesystem.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + ## Why this exists PHP's built-in file functions (`file_get_contents`, `fopen`, `mkdir`, etc.) are tightly coupled to the local disk. That's fine for simple scripts, but it creates a real problem when you want to: diff --git a/components/Git/README.md b/components/Git/README.md index 0cd7213d1..185344fc7 100644 --- a/components/Git/README.md +++ b/components/Git/README.md @@ -1,5 +1,10 @@ # Git + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/git.html](https://wordpress.github.io/php-toolkit/reference/git.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + ## Why this exists Git is typically used through the `git` binary — a compiled C program that reads and writes the repository on disk. That's perfect for most development workflows, but it breaks down in a few important scenarios: diff --git a/components/HTML/README.md b/components/HTML/README.md index a736e7918..991712289 100644 --- a/components/HTML/README.md +++ b/components/HTML/README.md @@ -1,5 +1,10 @@ # HTML + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/html.html](https://wordpress.github.io/php-toolkit/reference/html.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + ## Why this exists Modifying HTML in PHP usually means one of two things: string manipulation (fragile, breaks on any attribute ordering or whitespace variation) or loading the DOM extension (which requires libxml2, triggers errors on valid HTML5 that doesn't conform to XML rules, and mangles the document in the process). diff --git a/components/HttpClient/README.md b/components/HttpClient/README.md index c83b488ec..9dc76c4cc 100644 --- a/components/HttpClient/README.md +++ b/components/HttpClient/README.md @@ -1,5 +1,10 @@ # HttpClient + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/httpclient.html](https://wordpress.github.io/php-toolkit/reference/httpclient.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + An asynchronous HTTP client that works on vanilla PHP without requiring `curl` or any other extensions. It can use `curl` when available for better performance, but falls back to pure PHP sockets automatically. Supports concurrent requests, streaming responses, redirects, chunked encoding, gzip decompression, and basic auth. ## Installation diff --git a/components/HttpServer/README.md b/components/HttpServer/README.md index 51ab7623a..fcf713735 100644 --- a/components/HttpServer/README.md +++ b/components/HttpServer/README.md @@ -1,5 +1,10 @@ # HttpServer + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/httpserver.html](https://wordpress.github.io/php-toolkit/reference/httpserver.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + A minimal, blocking TCP-based HTTP server written in pure PHP. It is designed for CLI tools, local development servers, and test harnesses where you need a lightweight HTTP endpoint without pulling in a full web server. ## Installation diff --git a/components/Markdown/README.md b/components/Markdown/README.md index 813ca09c3..6cd11cf73 100644 --- a/components/Markdown/README.md +++ b/components/Markdown/README.md @@ -1,5 +1,10 @@ # Markdown + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/markdown.html](https://wordpress.github.io/php-toolkit/reference/markdown.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + Bidirectional converter between Markdown and WordPress block markup. Use `MarkdownConsumer` to parse Markdown (with optional YAML frontmatter) into WordPress blocks, and `MarkdownProducer` to serialize supported blocks back to Markdown. Designed for content synchronization workflows where a practical, structured conversion matters, such as three-way merging of static Markdown files with a WordPress database. It is not a byte-perfect Markdown formatter, and block attributes with no Markdown representation may be lost. ## Installation diff --git a/components/Merge/README.md b/components/Merge/README.md index 6bee05997..de3f2163f 100644 --- a/components/Merge/README.md +++ b/components/Merge/README.md @@ -1,5 +1,10 @@ # Merge + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/merge.html](https://wordpress.github.io/php-toolkit/reference/merge.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + A three-way merge and diff library for PHP. Given a common base version and two diverging branches, it computes diffs and merges the changes together, detecting conflicts along the way. The architecture is pluggable: swap out the differ (line-based or character-based), the merger (line-level or chunk-level), and add optional validation of the merged result. ## Installation diff --git a/components/Polyfill/README.md b/components/Polyfill/README.md index 276e3cd67..467f4f94a 100644 --- a/components/Polyfill/README.md +++ b/components/Polyfill/README.md @@ -1,5 +1,10 @@ # Polyfill + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/polyfill.html](https://wordpress.github.io/php-toolkit/reference/polyfill.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + Provides polyfills for PHP functions and WordPress core APIs so that WordPress-adjacent code can run in standalone PHP applications without a full WordPress installation. It backports PHP 8.0 string functions to PHP 7.2, stubs common WordPress escaping and translation functions, and implements a minimal but functional WordPress hook system (`add_filter`/`apply_filters`/`add_action`/`do_action`). ## Installation diff --git a/components/ToolkitCodingStandards/README.md b/components/ToolkitCodingStandards/README.md index b9d1ed88b..1bf4ede90 100644 --- a/components/ToolkitCodingStandards/README.md +++ b/components/ToolkitCodingStandards/README.md @@ -1,5 +1,10 @@ # ToolkitCodingStandards + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/coding-standards.html](https://wordpress.github.io/php-toolkit/reference/coding-standards.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + Custom PHP_CodeSniffer sniffs used internally by the PHP Toolkit project. This component provides two sniffs that enforce WordPress-style coding conventions: one requires Yoda-style comparisons (literal on the left side of `===`), and the other forbids the short ternary (Elvis) operator `?:`. Both sniffs support automatic fixing via `phpcbf`. This is internal tooling for the toolkit's own linter pipeline, not a general-purpose coding standard. diff --git a/components/XML/README.md b/components/XML/README.md index d0a215331..3d175763a 100644 --- a/components/XML/README.md +++ b/components/XML/README.md @@ -1,5 +1,10 @@ # XML + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/xml.html](https://wordpress.github.io/php-toolkit/reference/xml.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + ## Why this exists PHP ships with excellent XML support — `SimpleXML`, `DOMDocument`, `XMLReader` — but all of them rely on `libxml2`, a native C library. In most PHP environments that's fine. In WordPress Playground, which runs PHP compiled to WebAssembly in the browser, native extensions aren't available. You get the PHP standard library and nothing else. diff --git a/components/Zip/README.md b/components/Zip/README.md index 3b0c5232d..e7e80b5fd 100644 --- a/components/Zip/README.md +++ b/components/Zip/README.md @@ -1,5 +1,10 @@ # Zip + +> **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/zip.html](https://wordpress.github.io/php-toolkit/reference/zip.html) +> Snippets execute live in WordPress Playground — edit them in your browser and see real output. + + ## Why this exists PHP ships with `ZipArchive`, a convenient class for reading and writing ZIP files. The catch: it requires the `libzip` native extension, which isn't available everywhere. WordPress Playground compiles PHP to WebAssembly and runs it in the browser — no native extensions, no `libzip`, no `ZipArchive`. diff --git a/examples/create-wp-site/README.md b/examples/create-wp-site/README.md index 7f80b16d6..8dcbc445a 100644 --- a/examples/create-wp-site/README.md +++ b/examples/create-wp-site/README.md @@ -1,5 +1,9 @@ # Import Static Files Examples + +> **📚 Looking for runnable PHP Toolkit examples?** See **** — every component has a reference page with snippets that execute in WordPress Playground. + + This repository contains scripts and examples demonstrating how to import static files and documentation from various sources into your project using `bun` and custom scripts. ## Usage