From 8a7267e20baaa0878f0c0f5615a14e23e192089b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Sun, 3 May 2026 18:56:05 +0200 Subject: [PATCH] docs: surface the runnable docs site from every entry point MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Now that the docs site at https://wordpress.github.io/php-toolkit/ ships runnable examples for every component, link to it from the places a reader is likely to land: * Repo description + homepage URL on github.com/WordPress/php-toolkit (set via the API to https://wordpress.github.io/php-toolkit/). * Root README.md gets a "πŸ“š Live, runnable docs" callout at the top, a per-component table where each row links to both the README and the matching reference page on the live site, and a "build the docs site" section in the dev workflow. * Every components//README.md gets an idempotent docs-site banner immediately under the H1, deep-linking to that component's reference page (https://wordpress.github.io/php-toolkit/reference/.html). * Every components//composer.json gains a `homepage` field pointing at the same reference page, a `support` block with `issues`, `source`, and `docs` entries, and shared `keywords: [wordpress, php-toolkit]`. Packagist surfaces all of these on each package page, so readers landing on packagist.org/packages/wp-php-toolkit/zip can click straight through to the runnable docs. * The root composer.json (the meta-package wp-php-toolkit/php-toolkit) gets the same homepage + support block plus a description that names the docs URL. * examples/create-wp-site/README.md gets the same banner so readers who open the examples folder don't miss the docs site. * AGENTS.md gains a "Docs site:" pointer so coding agents know where the runnable examples live and that bin/_docs_components/.md is where to edit them. No code changes; all 87 snippets still pass `bin/run-snippets.py --check`. The 18 component banners are inserted via a simple marker ( ... ), so future URL/wording updates can be reapplied idempotently. --- AGENTS.md | 3 + README.md | 62 +++++++++++++-------- components/BlockParser/README.md | 5 ++ components/BlockParser/composer.json | 22 ++++++-- components/Blueprints/README.md | 5 ++ components/Blueprints/composer.json | 10 ++++ components/ByteStream/README.md | 5 ++ components/ByteStream/composer.json | 16 +++++- components/CLI/README.md | 5 ++ components/CLI/composer.json | 10 ++++ components/CORSProxy/README.md | 5 ++ components/CORSProxy/composer.json | 16 +++++- components/DataLiberation/README.md | 5 ++ components/DataLiberation/composer.json | 10 ++++ components/Encoding/README.md | 5 ++ components/Encoding/composer.json | 10 ++++ components/Filesystem/README.md | 5 ++ components/Filesystem/composer.json | 16 +++++- components/Git/README.md | 5 ++ components/Git/composer.json | 16 +++++- components/HTML/README.md | 5 ++ components/HTML/composer.json | 16 +++++- components/HttpClient/README.md | 5 ++ components/HttpClient/composer.json | 16 +++++- components/HttpServer/README.md | 5 ++ components/HttpServer/composer.json | 16 +++++- components/Markdown/README.md | 5 ++ components/Markdown/composer.json | 10 ++++ components/Merge/README.md | 5 ++ components/Merge/composer.json | 26 ++++++--- components/Polyfill/README.md | 5 ++ components/Polyfill/composer.json | 10 ++++ components/ToolkitCodingStandards/README.md | 5 ++ components/XML/README.md | 5 ++ components/XML/composer.json | 16 +++++- components/Zip/README.md | 5 ++ components/Zip/composer.json | 16 +++++- composer.json | 10 +++- examples/create-wp-site/README.md | 4 ++ 39 files changed, 356 insertions(+), 65 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e43a27039..063b03fcb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,9 @@ into WordPress plugins under `plugins/`. Upstream: https://github.com/WordPress/php-toolkit Branch: `trunk` (not `main`) +Docs site: https://wordpress.github.io/php-toolkit/ β€” runnable examples per +component, sourced from `bin/_docs_components/.md`. Edit those files +to change the snippets that ship and the captured output that CI verifies. ## Commands diff --git a/README.md b/README.md index 959f69ee5..217e20bcb 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,36 @@ ## 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 snippets 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 for 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, 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 there is executable in-browser and is verified against `trunk` in CI on every PR. ### Using the Blueprints v2 runner @@ -30,17 +49,17 @@ how the runner is implemented. ### 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 +# ... ``` +Each Packagist page links back to its component's reference page so you can browse runnable examples without leaving the package listing. + #### 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). @@ -112,17 +131,16 @@ To fix the linting errors, run: composer lint-fix ``` -#### Composer +#### Building the docs site -The root composer.json file is an amalgamation of composer.base.json all -component composer.json files. To regenerate it, run: +The docs site under `docs/` is generated from `bin/_docs_components/.md`. To rebuild and preview locally: ```sh -bin/regenerate_composer.json.php +bash bin/build-docs-bundle.sh # bundles toolkit + regenerates HTML +python3 bin/serve-docs.py # opens http://localhost:8787 ``` -This will merge all the package-specific dependencies and the autoload rules into -the root composer.json file. +Snippets in the markdown sources run in CI on every PR (see `.github/workflows/snippet-tests.yml`) and in WordPress Playground from the live site. ### Windows compatibility diff --git a/components/BlockParser/README.md b/components/BlockParser/README.md index fa0d7b2b6..54f0b7274 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + ## 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/BlockParser/composer.json b/components/BlockParser/composer.json index 62e30c9e3..9be06fc58 100644 --- a/components/BlockParser/composer.json +++ b/components/BlockParser/composer.json @@ -3,9 +3,11 @@ "description": "BlockParser component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", - "require": { - "php": ">=7.2" - }, + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/blockparser.html", "authors": [ { "name": "Adam Zielinski", @@ -16,6 +18,17 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/blockparser.html" + }, + "require": { + "php": ">=7.2" + }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "." @@ -23,8 +36,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/Blueprints/README.md b/components/Blueprints/README.md index 23f4519eb..1ffd71e26 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/Blueprints/composer.json b/components/Blueprints/composer.json index 8eec254b7..a5e312373 100644 --- a/components/Blueprints/composer.json +++ b/components/Blueprints/composer.json @@ -3,6 +3,11 @@ "description": "Blueprints component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/blueprints.html", "authors": [ { "name": "Adam Zielinski", @@ -13,6 +18,11 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/blueprints.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/bytestream": "^0.8", diff --git a/components/ByteStream/README.md b/components/ByteStream/README.md index 30809cef4..a9bede580 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/ByteStream/composer.json b/components/ByteStream/composer.json index 1856fcb18..0f385283c 100644 --- a/components/ByteStream/composer.json +++ b/components/ByteStream/composer.json @@ -3,6 +3,11 @@ "description": "ByteStream component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/bytestream.html", "authors": [ { "name": "Adam Zielinski", @@ -13,9 +18,17 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/bytestream.html" + }, "require": { "php": ">=7.2" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -23,8 +36,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/CLI/README.md b/components/CLI/README.md index a9a1047fc..6bd7483e3 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/CLI/composer.json b/components/CLI/composer.json index 6b6b35733..ff9972b23 100644 --- a/components/CLI/composer.json +++ b/components/CLI/composer.json @@ -3,6 +3,11 @@ "description": "CLI component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/cli.html", "authors": [ { "name": "Adam Zielinski", @@ -13,6 +18,11 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/cli.html" + }, "require": { "php": ">=7.2" }, diff --git a/components/CORSProxy/README.md b/components/CORSProxy/README.md index d91e033cd..51f58e56a 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/CORSProxy/composer.json b/components/CORSProxy/composer.json index fc1c2fafc..40dc34810 100644 --- a/components/CORSProxy/composer.json +++ b/components/CORSProxy/composer.json @@ -3,6 +3,11 @@ "description": "CORSProxy component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/corsproxy.html", "authors": [ { "name": "Adam Zielinski", @@ -13,9 +18,17 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/corsproxy.html" + }, "require": { "php": ">=7.2" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "psr-4": { "WordPress\\CORSProxy\\": "" @@ -23,8 +36,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/DataLiberation/README.md b/components/DataLiberation/README.md index e260a2fec..a41b34831 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/DataLiberation/composer.json b/components/DataLiberation/composer.json index cf29dd30d..4184c8e3d 100644 --- a/components/DataLiberation/composer.json +++ b/components/DataLiberation/composer.json @@ -3,6 +3,11 @@ "description": "Data Liberation component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/dataliberation.html", "authors": [ { "name": "Adam Zielinski", @@ -13,6 +18,11 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/dataliberation.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/bytestream": "^0.8", diff --git a/components/Encoding/README.md b/components/Encoding/README.md index add937614..c1a72b642 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/Encoding/composer.json b/components/Encoding/composer.json index 0d127a74c..a2548436f 100644 --- a/components/Encoding/composer.json +++ b/components/Encoding/composer.json @@ -3,6 +3,11 @@ "description": "Encoding component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/encoding.html", "authors": [ { "name": "Adam Zielinski", @@ -13,6 +18,11 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/encoding.html" + }, "require": { "php": ">=7.2" }, diff --git a/components/Filesystem/README.md b/components/Filesystem/README.md index 153d0e525..b6442971a 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + ## 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/Filesystem/composer.json b/components/Filesystem/composer.json index 01fb13cc2..513c9e49c 100644 --- a/components/Filesystem/composer.json +++ b/components/Filesystem/composer.json @@ -3,6 +3,11 @@ "description": "Filesystem component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/filesystem.html", "authors": [ { "name": "Adam Zielinski", @@ -13,10 +18,18 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/filesystem.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/bytestream": "^0.8" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -27,8 +40,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/Git/README.md b/components/Git/README.md index 0cd7213d1..f6128fb09 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + ## 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/Git/composer.json b/components/Git/composer.json index f99016e1e..706db2d3a 100644 --- a/components/Git/composer.json +++ b/components/Git/composer.json @@ -3,6 +3,11 @@ "description": "Git component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/git.html", "authors": [ { "name": "Adam Zielinski", @@ -13,12 +18,20 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/git.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/bytestream": "^0.8", "wp-php-toolkit/filesystem": "^0.8", "wp-php-toolkit/http-client": "^0.8" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -29,8 +42,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/HTML/README.md b/components/HTML/README.md index a736e7918..3f4ebd90b 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + ## 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/HTML/composer.json b/components/HTML/composer.json index 1045cc45a..165207c7f 100644 --- a/components/HTML/composer.json +++ b/components/HTML/composer.json @@ -3,6 +3,11 @@ "description": "HTML component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/html.html", "authors": [ { "name": "Adam Zielinski", @@ -13,9 +18,17 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/html.html" + }, "require": { "php": ">=7.2" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -24,8 +37,5 @@ "/Tests/", "/html5-named-character-references.php" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/HttpClient/README.md b/components/HttpClient/README.md index c83b488ec..0e4e86338 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/HttpClient/composer.json b/components/HttpClient/composer.json index 0391c71b9..4ed442bfe 100644 --- a/components/HttpClient/composer.json +++ b/components/HttpClient/composer.json @@ -3,6 +3,11 @@ "description": "HttpClient component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/httpclient.html", "authors": [ { "name": "Adam Zielinski", @@ -13,12 +18,20 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/httpclient.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/data-liberation": "^0.8", "wp-php-toolkit/bytestream": "^0.8", "wp-php-toolkit/filesystem": "^0.8" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -26,8 +39,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/HttpServer/README.md b/components/HttpServer/README.md index 51ab7623a..9277b9848 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/HttpServer/composer.json b/components/HttpServer/composer.json index 8253a1547..26edd08d7 100644 --- a/components/HttpServer/composer.json +++ b/components/HttpServer/composer.json @@ -3,6 +3,11 @@ "description": "HttpServer component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/httpserver.html", "authors": [ { "name": "Adam Zielinski", @@ -13,12 +18,20 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/httpserver.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/bytestream": "^0.8", "wp-php-toolkit/data-liberation": "^0.8", "wp-php-toolkit/http-client": "^0.8" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -26,8 +39,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/Markdown/README.md b/components/Markdown/README.md index 813ca09c3..6b7a1c273 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/Markdown/composer.json b/components/Markdown/composer.json index ee47fc277..dc3d4e41f 100644 --- a/components/Markdown/composer.json +++ b/components/Markdown/composer.json @@ -3,6 +3,11 @@ "description": "Markdown component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/markdown.html", "authors": [ { "name": "Adam Zielinski", @@ -13,6 +18,11 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/markdown.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/data-liberation": "^0.8", diff --git a/components/Merge/README.md b/components/Merge/README.md index 6bee05997..2e386a028 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/Merge/composer.json b/components/Merge/composer.json index cf4514695..4f58f4bc4 100644 --- a/components/Merge/composer.json +++ b/components/Merge/composer.json @@ -3,16 +3,21 @@ "description": "Merge component for WordPress with configurable diffing and merging strategies.", "type": "library", "license": "GPL-2.0-or-later", - "autoload": { - "classmap": [ - "./" - ] - }, + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/merge.html", "authors": [ { "name": "WordPress Contributors" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/merge.html" + }, "require": { "php": ">=7.4", "yetanotherape/diff-match-patch": "^1.0", @@ -25,12 +30,17 @@ "wp-coding-standards/wpcs": "^2.3", "phpstan/phpstan": "^1.0" }, + "autoload": { + "classmap": [ + "./" + ] + }, + "config": { + "sort-packages": true + }, "scripts": { "test": "phpunit", "cs": "phpcs", "cs-fix": "phpcbf" - }, - "config": { - "sort-packages": true } } diff --git a/components/Polyfill/README.md b/components/Polyfill/README.md index 276e3cd67..a351d3d74 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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/Polyfill/composer.json b/components/Polyfill/composer.json index 693d2c5f1..73bd00a10 100644 --- a/components/Polyfill/composer.json +++ b/components/Polyfill/composer.json @@ -3,6 +3,11 @@ "description": "Polyfill component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/polyfill.html", "authors": [ { "name": "Adam Zielinski", @@ -13,6 +18,11 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/polyfill.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/blockparser": "^0.8", diff --git a/components/ToolkitCodingStandards/README.md b/components/ToolkitCodingStandards/README.md index b9d1ed88b..e1e77e79c 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + 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..56d196000 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + ## 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/XML/composer.json b/components/XML/composer.json index d3afebb7a..226191126 100644 --- a/components/XML/composer.json +++ b/components/XML/composer.json @@ -3,6 +3,11 @@ "description": "XML component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/xml.html", "authors": [ { "name": "Adam Zielinski", @@ -13,10 +18,18 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/xml.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/encoding": "^0.8" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -24,8 +37,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/components/Zip/README.md b/components/Zip/README.md index 3b0c5232d..81527c9a6 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) +> Open the page to edit each snippet in your browser and run it in WordPress Playground. + + ## 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/components/Zip/composer.json b/components/Zip/composer.json index e0bf2cb47..fecb0bae1 100644 --- a/components/Zip/composer.json +++ b/components/Zip/composer.json @@ -3,6 +3,11 @@ "description": "Zip component for WordPress.", "type": "library", "license": "GPL-2.0-or-later", + "keywords": [ + "wordpress", + "php-toolkit" + ], + "homepage": "https://wordpress.github.io/php-toolkit/reference/zip.html", "authors": [ { "name": "Adam Zielinski", @@ -13,12 +18,20 @@ "email": "wordpress@wordpress.org" } ], + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/reference/zip.html" + }, "require": { "php": ">=7.2", "wp-php-toolkit/bytestream": "^0.8", "wp-php-toolkit/filesystem": "^0.8", "wp-php-toolkit/http-client": "^0.8" }, + "require-dev": { + "phpunit/phpunit": "^9.5" + }, "autoload": { "classmap": [ "./" @@ -29,8 +42,5 @@ "exclude-from-classmap": [ "/Tests/" ] - }, - "require-dev": { - "phpunit/phpunit": "^9.5" } } diff --git a/composer.json b/composer.json index 6d52bb4b3..a2808b657 100644 --- a/composer.json +++ b/composer.json @@ -1,12 +1,18 @@ { "name": "wp-php-toolkit/php-toolkit", "type": "library", - "description": "WordPress Components", + "description": "Standalone, dependency-free PHP libraries for WordPress and PHP projects β€” XML, ZIP, Git, HTTP, Markdown, Filesystem, and more. Browse runnable examples at https://wordpress.github.io/php-toolkit/", "keywords": [ "wordpress", + "php-toolkit", "components" ], - "homepage": "https://wordpress.org", + "homepage": "https://wordpress.github.io/php-toolkit/", + "support": { + "issues": "https://github.com/WordPress/php-toolkit/issues", + "source": "https://github.com/WordPress/php-toolkit", + "docs": "https://wordpress.github.io/php-toolkit/" + }, "license": "GPL-2.0-or-later", "authors": [ { diff --git a/examples/create-wp-site/README.md b/examples/create-wp-site/README.md index 7f80b16d6..a6d867ea6 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 live 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