### Run Project Examples

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Execute the provided shell script to run all examples. Ensure `bun` is installed before running the script.

```bash
./run-examples.sh
```

--------------------------------

### Import Gutenberg Documentation

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Demonstrates importing Gutenberg documentation from its Git repository. This snippet includes examples for importing a subset focused on data basics and the complete documentation.

```bash
bun index.js \
  git https://github.com/WordPress/gutenberg.git \
  --branch=trunk \
  --path-in-repo=docs/how-to-guides/data-basics/ \
  --media-url=https://developer.wordpress.org/files/ \
  --media-url=https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/ \
  --source-site-url=https://developer.wordpress.org/block-editor/how-to-guides/data-basics/ \
  --additional-site-urls=https://developer.wordpress.org/docs/how-to-guides/data-basics/
```

```bash
bun index.js \
  git https://github.com/WordPress/gutenberg.git \
  --branch=trunk \
  --path-in-repo=docs/ \
  --media-url=https://developer.wordpress.org/files/ \
  --media-url=https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/ \
  --source-site-url=https://developer.wordpress.org/block-editor/ \
  --additional-site-urls=https://developer.wordpress.org/docs/
```

--------------------------------

### Define and Access Configuration with Schema Validation in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/league/config/README.md

This comprehensive example demonstrates how to define a strict configuration schema using `League\Config\Configuration` and `Nette\Schema\Expect`, set configuration values using `merge()` and `set()`, and retrieve them with `get()`. It also illustrates automatic validation, default value application, and exception handling for invalid or non-existent keys.

```php
use League\Config\Configuration;
use Nette\Schema\Expect;

// Define your configuration schema
$config = new Configuration([
    'database' => Expect::structure([
        'driver' => Expect::anyOf('mysql', 'postgresql', 'sqlite')->required(),
        'host' => Expect::string()->default('localhost'),
        'port' => Expect::int()->min(1)->max(65535),
        'ssl' => Expect::bool(),
        'database' => Expect::string()->required(),
        'username' => Expect::string()->required(),
        'password' => Expect::string()->nullable(),
    ]),
    'logging' => Expect::structure([
        'enabled' => Expect::bool()->default($_ENV['DEBUG'] == true),
        'file' => Expect::string()->deprecated("use logging.path instead"),
        'path' => Expect::string()->assert(function ($path) { return \is_writeable($path); })->required(),
    ]),
]);

// Set the values, either all at once with `merge()`:
$config->merge([
    'database' => [
        'driver' => 'mysql',
        'port' => 3306,
        'database' => 'mydb',
        'username' => 'user',
        'password' => 'secret',
    ],
]);

// Or one-at-a-time with `set()`:
$config->set('logging.path', '/var/log/myapp.log');

// You can now retrieve those values with `get()`.
// Validation and defaults will be applied for you automatically
$config->get('database');        // Fetches the entire "database" section as an array
$config->get('database.driver'); // Fetch a specific nested value with dot notation
$config->get('database/driver'); // Fetch a specific nested value with slash notation
$config->get('database.host');   // Returns the default value "localhost"
$config->get('logging.path');    // Guaranteed to be writeable thanks to the assertion in the schema

// If validation fails an `InvalidConfigurationException` will be thrown:
$config->set('database.driver', 'mongodb');
$config->get('database.driver'); // InvalidConfigurationException

// Attempting to fetch a non-existent key will result in an `InvalidConfigurationException`
$config->get('foo.bar');

// You could avoid this by checking whether that item exists:
$config->exists('foo.bar'); // Returns `false`
```

--------------------------------

### Install PHP Toolkit Libraries via Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/README.md

This composer.json configuration demonstrates the minimal setup required to include the WordPress/php-toolkit libraries in a non-WordPress project. It specifies the package name, the required toolkit version, and the GitHub repository as a source.

```json
{
	"name": "my-namespace/my-package",
	"require": {
		"WordPress/php-toolkit": "^v0.0.21-alpha"
	},
	"repositories": [
		{
			"type": "github",
			"url": "https://github.com/WordPress/php-toolkit"
		}
	]
}
```

--------------------------------

### Install webuni/front-matter via Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This snippet provides the command-line instruction to install the `webuni/front-matter` library using Composer, the PHP dependency manager.

```php
composer require webuni/front-matter
```

--------------------------------

### Install league/commonmark with Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/league/commonmark/README.md

This snippet shows how to install the league/commonmark library using Composer. It requires PHP 7.4 or higher with the `mbstring` extension.

```bash
$ composer require league/commonmark
```

--------------------------------

### Install league/config with Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/league/config/README.md

This snippet shows how to install the league/config library using Composer, which requires PHP 7.4 or higher.

```bash
composer require league/config
```

--------------------------------

### Import Laravel Documentation

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports Laravel documentation from its GitHub repository, targeting the `12.x` branch for the latest documentation.

```bash
bun index.js \
  git https://github.com/laravel/docs.git \
  --path-in-repo=/ \
  --branch=12.x \
  --source-site-url=https://laravel.com/docs/
```

--------------------------------

### Basic Data Manipulation with Dot Access in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/dflydev/dot-access-data/README.md

This example demonstrates fundamental operations like setting, getting, appending, and checking existence of data using dot notation. It also shows how to handle missing paths with and without default values, illustrating the MissingPathException.

```PHP
use Dflydev\DotAccessData\Data;

$data = new Data;

$data->set('a.b.c', 'C');
$data->set('a.b.d', 'D1');
$data->append('a.b.d', 'D2');
$data->set('a.b.e', ['E0', 'E1', 'E2']);

// C
$data->get('a.b.c');

// ['D1', 'D2']
$data->get('a.b.d');

// ['E0', 'E1', 'E2']
$data->get('a.b.e');

// true
$data->has('a.b.c');

// false
$data->has('a.b.d.j');


// 'some-default-value'
$data->get('some.path.that.does.not.exist', 'some-default-value');

// throws a MissingPathException because no default was given
$data->get('some.path.that.does.not.exist');
```

--------------------------------

### Install PHP Diff-Match-Patch Library via Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Merge/vendor-patched/yetanotherape/diff-match-patch/README.md

This command installs the `yetanotherape/diff-match-patch` library into your PHP project using Composer. Ensure Composer is installed and accessible in your environment before running this command.

```Shell
composer require yetanotherape/diff-match-patch
```

--------------------------------

### Import Fullstack GraphQL Book Content

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports content from the Fullstack GraphQL book's GitHub repository, targeting the `manuscript/` directory on the `master` branch.

```bash
bun index.js \
  git https://github.com/GraphQLCollege/fullstack-graphql.git \
  --branch=master \
  --path-in-repo=manuscript/ \
  --source-site-url=https://raw.githubusercontent.com/GraphQLCollege/fullstack-graphql/refs/heads/master/manuscript/
```

--------------------------------

### Import CPP WASM Book Content

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports content from the CPP WASM book's GitHub repository, targeting the `en/` directory on the `master` branch.

```bash
bun index.js \
  git https://github.com/3dgen/cppwasm-book.git \
  --branch=master \
  --path-in-repo=en/ \
  --source-site-url=https://raw.githubusercontent.com/3dgen/cppwasm-book/refs/heads/master/en/
```

--------------------------------

### Import Bootstrap 5.3 Documentation

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports Bootstrap 5.3 documentation from its GitHub repository, specifically targeting the `gh-pages` branch for the documentation files.

```bash
bun index.js \
  git https://github.com/twbs/bootstrap.git \
  --branch=gh-pages \
  --path-in-repo=docs/5.3/ \
  --media-url=https://getbootstrap.com/docs/5.3/ \
  --source-site-url=https://getbootstrap.com/docs/5.3/ \
  --additional-site-urls=https://getbootstrap.com/docs/
```

--------------------------------

### Import WordPress Playground Blueprints Tutorial

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports documentation for the Blueprints tutorial from the WordPress Playground project's GitHub repository, showcasing integration with other WordPress-related projects.

```bash
bun index.js \
  git https://github.com/WordPress/wordpress-playground.git \
  --branch=trunk \
  --path-in-repo=packages/docs/site/docs/blueprints/ \
  --media-url=https://wordpress.github.io/wordpress-playground/ \
  --source-site-url=https://wordpress.github.io/
```

--------------------------------

### Import Content from EPUB File

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports content from a specified EPUB file hosted on GitHub, demonstrating the capability to process EPUB formatted documents.

```bash
bun index.js epub https://github.com/IDPF/epub3-samples/releases/download/20230704/childrens-literature.epub
```

--------------------------------

### Simple WordPress Blueprint Example

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

A basic example of a WordPress Blueprint JSON document, illustrating how to specify WordPress version, plugins, themes, custom post types, and constants for a site configuration.

```JSON
{
	"wordpressVersion": "6.6",
	"plugins": ["jetpack", "https://woo.com/woocommerce.zip"],
	"themes": ["./wp-content/themes/adventurer/"],
	"postTypes": {
		"book": { "label": "Book" }
	},
	"constants": {
		"WP_DEBUG": true
	}
}
```

--------------------------------

### Install Nette Utils PHP Package

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/nette/utils/readme.md

This command installs the Nette Utils package into your PHP project using Composer, the dependency manager for PHP. It ensures all necessary files and dependencies are downloaded and configured for use.

```Composer
composer require nette/utils
```

--------------------------------

### Example Directory Layout for Bundled Static Content

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

This example illustrates the recommended directory structure for organizing static content files (posts and pages) within a Blueprint Bundle. These files are then referenced from the `blueprint.json` for import.

```Filesystem Layout
wp-content/
└─── content/
     └─── posts/
          └─── posts/
               └─── 2025-05-02-launching-a-new-website.html
          └─── pages/
               └─── about-us.html
```

--------------------------------

### Install IDNA Library using Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/idna/README.md

Instructions on how to install the IDNA library using Composer, a dependency manager for PHP. This command adds the 'rowbot/idna' package to your project's dependencies.

```bash
composer require rowbot/idna
```

--------------------------------

### Import CPython Internal Documentation

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports internal documentation from the CPython project's GitHub repository, specifically from the `InternalDocs/` directory on the `main` branch.

```bash
bun index.js \
  git https://github.com/python/cpython.git \
  --branch=main \
  --path-in-repo=InternalDocs/ \
  --source-site-url=https://raw.githubusercontent.com/python/cpython/refs/heads/main/InternalDocs/
```

--------------------------------

### Import Gutenberg Documentation from Local Path

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports Gutenberg documentation directly from a local repository checkout path, useful for development workflows where the source is local.

```bash
bun index.js path ../../../gutenberg/docs/how-to-guides/
```

--------------------------------

### Import Accessibility Testing Content (WXR)

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports accessibility testing content from a WordPress XML export file (WXR format) hosted on GitHub.

```bash
bun index.js wxr https://raw.githubusercontent.com/wpaccessibility/a11y-theme-unit-test/master/a11y-theme-unit-test-data.xml
```

--------------------------------

### Install Nette Schema via Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/nette/schema/readme.md

This snippet shows how to install the Nette Schema library using Composer, the PHP dependency manager.

```Shell
composer require nette/schema
```

--------------------------------

### Install PSR Log Package via Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/psr/log/README.md

This snippet shows the command to install the `psr/log` package using Composer, the dependency manager for PHP. This package provides the `LoggerInterface` which defines the standard for logging.

```Bash
composer require psr/log
```

--------------------------------

### Import WordPress Theme Unit Test Data (WXR)

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports standard WordPress theme unit test data from a WXR file hosted on GitHub, useful for theme development and testing.

```bash
bun index.js wxr https://raw.githubusercontent.com/WordPress/theme-test-data/master/themeunittestdata.wordpress.xml
```

--------------------------------

### Install URL-Parser PHP Library with Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/url/README.md

This command installs the `rowbot/url` package, a WHATWG URL spec compliant parser, using Composer. It's the primary method for integrating the library into PHP projects.

```bash
composer require rowbot/url
```

--------------------------------

### Example Usage of PSR Log LoggerInterface in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/psr/log/README.md

This PHP example demonstrates how to integrate and use the `Psr\Log\LoggerInterface` within a class. It illustrates dependency injection for the logger, logging informational messages, and handling exceptions by logging errors with additional context.

```PHP
<?php

use Psr\Log\LoggerInterface;

class Foo
{
    private $logger;

    public function __construct(LoggerInterface $logger = null)
    {
        $this->logger = $logger;
    }

    public function doSomething()
    {
        if ($this->logger) {
            $this->logger->info('Doing work');
        }

        try {
            $this->doSomethingElse();
        } catch (Exception $exception) {
            $this->logger->error('Oh no!', array('exception' => $exception));
        }

        // do something useful
    }
}
```

--------------------------------

### PHP Asynchronous HTTP Client Usage Example

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/HttpClient/README.md

This PHP example illustrates how to perform multiple asynchronous HTTP requests using the client library. It demonstrates initializing `Request` objects, creating an optimized client via `Client::create()`, enqueuing requests, and then continuously processing events like `Client::EVENT_BODY_CHUNK_AVAILABLE` to handle incoming response data chunks. This allows for efficient, non-blocking I/O operations.

```php
$requests = [
    new Request("[https://wordpress.org/latest.zip](https://wordpress.org/latest.zip)"),
    new Request("[https://raw.githubusercontent.com/wpaccessibility/a11y-theme-unit-test/master/a11y-theme-unit-test-data.xml](https://raw.githubusercontent.com/wpaccessibility/a11y-theme-unit-test/master/a11y-theme-unit-test-data.xml)"),
];

// Creates the most appropriate client based for your environment.
$client = Client::create();
$client->enqueue($requests);

while ($client->await_next_event()) {
    $event = $client->get_event();
    $request = $client->get_request();

    if ($event === Client::EVENT_BODY_CHUNK_AVAILABLE) {
        $chunk = $client->get_response_body_chunk();
        // Process the chunk...
    }
    // Handle other events...
}
```

--------------------------------

### Install PSR Log with Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/vendor-patched/log/README.md

This snippet shows how to install the PSR Log package using Composer, the dependency manager for PHP. This command adds the `psr/log` package as a dependency to your project.

```bash
composer require psr/log
```

--------------------------------

### Hypothetical WooCommerce Blueprint Property Example

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

An example of a hypothetical Blueprint property for WooCommerce products, demonstrating a non-standard extension that would require transpilation into core Blueprint properties before execution.

```JSON
{
	"products": [
		{
			"name": "T-shirt",
			"price": 100
		}
	]
}
```

--------------------------------

### Install Punycode PHP Library

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/punycode/README.md

This command installs the Punycode PHP library using Composer, a dependency manager for PHP. It adds the `rowbot/punycode` package to your project's dependencies, making its functionalities available for use.

```bash
composer require rowbot/punycode
```

--------------------------------

### PHP URL Class Constructor Usage Examples

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/url/README.md

Demonstrates how to instantiate the `Rowbot\URL\URL` object in PHP. Examples include constructing from absolute URLs, relative URLs with a base, using existing URL objects, and handling `TypeError` exceptions for invalid URL inputs.

```php
use Rowbot\URL\URL;

// Construct a new URL object.
$url = new URL('https://example.com/');

// Construct a new URL object using a relative URL, by also providing the constructor with the base URL.
$url = new URL('path/to/file.php?query=string', 'http://example.com');
echo $url->href; // Outputs: "http://example.com/path/to/file.php?query=string"

// You can also pass an existing URL object to either the $url or $base arguments.
$url = new URL('https://example.org:123');
$url1 = new URL('foo/bar/', $url);
echo $url1->href; // Outputs: "https://example.org:123/foo/bar/"

// Catch the error when URL parsing fails.
try {
    $url = new URL('http://2001::1]');
} catch (\Rowbot\URL\Exception\TypeError $e) {
    echo 'Invalid URL';
}
```

--------------------------------

### Import Content from Adam's Blog via Crawler

Source: https://github.com/wordpress/php-toolkit/blob/trunk/examples/create-wp-site/README.md

Imports content from Adam's blog using a web crawler. This method successfully imports media files and internal links, though HTML to Block markup conversion and header/footer inclusion may require further refinement.

```bash
bun examples/create-wp-site/index.js crawler https://adamadam.blog
```

--------------------------------

### Example of Idna::toUnicode Usage

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/idna/README.md

Demonstrates how to use the `Idna::toUnicode` method to convert a Punycode domain name to its Unicode representation and retrieve the transformed domain.

```php
use Rowbot\Idna\Idna;

$result = Idna::toUnicode('xn---with-SUPER-MONKEYS-pc58ag80a8qai00g7n9n.com');
echo $result->getDomain(); // 安室奈美恵-with-super-monkeys.com
```

--------------------------------

### Example Markdown File with YAML Front Matter

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This snippet provides a common example of a Markdown file incorporating YAML front matter at the top. The front matter typically contains metadata like layout, title, and tags.

```markdown
---
layout: post
title: I Love Markdown
tags:
    - test
    - example
---

# Hello World!
```

--------------------------------

### Example of Local Path Rewriting in Static Content

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

This example illustrates how local relative paths within static content are automatically resolved and rewritten to absolute, correct URLs during the Blueprint execution process. The first block shows the original content, and the second block shows the content after URL rewriting.

```text
Welcome to the bike shop! Learn more about our [bikes](./about-bikes.html).
```

```text
Welcome to the bike shop! Learn more about our [bikes](/2025/05/02/about-bikes.html).
```

--------------------------------

### Examples of Front Matter Formats (YAML, TOML, JSON)

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This section illustrates the syntax for different front matter formats supported by the library, including YAML (or Neon), TOML, and JSON, embedded within a markdown-like structure.

```markdown
```markdown
---
foo: bar
---

# h1

paragraph
```
```

```markdown
```markdown
+++
foo = bar
+++

# h1

paragraph
```
```

```markdown
```markdown
{
"foo": "bar"
}

# h1

paragraph
```
```

--------------------------------

### Normalizing Data with `before()` in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/nette/schema/readme.md

Demonstrates using the `before()` method to normalize data prior to the validation itself. This example transforms a space-separated string into an array of strings.

```php
$explode = fn($v) => explode(' ', $v);

$schema = Expect::arrayOf('string')
	->before($explode);

$normalized = $processor->process($schema, 'a b c');
// OK, returns ['a', 'b', 'c']
```

--------------------------------

### Transpiled WooCommerce Blueprint Example

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

The transpiled version of the hypothetical WooCommerce Blueprint, showing how custom properties are converted into standard core Blueprint properties like plugins and content for compatibility and runner portability.

```JSON
{
	"plugins": ["woocommerce"],
	"content": [
		{
			"type": "posts",
			"source": [
				{
					"title": "T-shirt",
					"content": "This is a T-shirt",
					"post_type": "product",
					"post_status": "publish"
				}
			]
		}
	]
}
```

--------------------------------

### Blueprint Validation Error Message Examples

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

These examples illustrate the difference between a bad and a good error message during Blueprint validation. Good error messages are clear, pinpoint the issue, and offer guidance for resolution, unlike vague or technical error messages.

```Generic
Invalid blueprint: value of tag "step" **MUST** be in oneOf at /additionalStepsAfterExecution/0
```

```Generic
"intallPlugi" defined in additionalStepsAfterExecution[0] is not one of supported Blueprint steps.

Did you mean "installPlugin"? See the list of supported Blueprint steps at
https://wordpress.github.io/wordpress-playground/blueprints/steps/
```

--------------------------------

### Managing Nested Data Structures with Dot Access in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/dflydev/dot-access-data/README.md

This example showcases how to manage more complex, nested data structures like host configurations. It illustrates retrieving specific values, accessing sub-data as DataInterface instances, removing entries, and appending to arrays, demonstrating practical application of the library.

```PHP
use Dflydev\DotAccessData\Data;

$data = new Data([
    'hosts' => [
        'hewey' => [
            'username' => 'hman',
            'password' => 'HPASS',
            'roles'    => ['web']
        ],
        'dewey' => [
            'username' => 'dman',
            'password' => 'D---S',
            'roles'    => ['web', 'db'],
            'nick'     => 'dewey dman'
        ],
        'lewey' => [
            'username' => 'lman',
            'password' => 'LP@$$',
            'roles'    => ['db']
        ]
    ]
]);

// hman
$username = $data->get('hosts.hewey.username');
// HPASS
$password = $data->get('hosts.hewey.password');
// ['web']
$roles = $data->get('hosts.hewey.roles');
// dewey dman
$nick = $data->get('hosts.dewey.nick');
// Unknown
$nick = $data->get('hosts.lewey.nick', 'Unknown');

// DataInterface instance
$dewey = $data->getData('hosts.dewey');
// dman
$username = $dewey->get('username');
// D---S
$password = $dewey->get('password');
// ['web', 'db']
$roles = $dewey->get('roles');

// No more lewey
$data->remove('hosts.lewey');

// Add DB to hewey's roles
$data->append('hosts.hewey.roles', 'db');

$data->set('hosts.april', [
    'username' => 'aman',
    'password' => '@---S',
    'roles'    => ['web']
]);

// Check if a key exists (true to this case)
$hasKey = $data->has('hosts.dewey.username');
```

--------------------------------

### Example Blueprint Configuration and Generated Execution Plan

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

This snippet illustrates how a declarative Blueprint configuration is translated by the runner into an imperative execution plan. Properties like 'phpVersion' and 'wordpressVersion' are handled during validation and target resolution, thus not appearing in the final execution plan.

```JSON
{
	"phpVersion": "8.1",
	"wordpressVersion": "6.4",
	"plugins": ["jetpack"],
	"constants": { "WP_DEBUG": true },
	"additionalStepsAfterExecution": [{ "step": "installPlugin", "slug": "akismet" }]
}
```

```JSON
{
	"additionalStepsAfterExecution": [
		{ "step": "defineConstants", "constants": { "WP_DEBUG": true } },
		{ "step": "installPlugin", "slug": "jetpack", "activate": true },
		{ "step": "installPlugin", "slug": "akismet" }
	]
}
```

--------------------------------

### Referencing Plugins with Relative Paths in Blueprint JSON

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

This JSON snippet demonstrates how a `blueprint.json` file can reference plugins using relative paths. It shows two examples: a zipped plugin (`akismet.zip`) and a directory-based plugin (`classic-editor`), both located within the Blueprint's Execution Context.

```JSON
{
	"plugins": [
		"./wp-content/plugins/akismet.zip",
		"./wp-content/plugins/classic-editor"
	]
}
```

--------------------------------

### Install PHP Toolkit Libraries at Specific Commit/Tag

Source: https://github.com/wordpress/php-toolkit/blob/trunk/README.md

This composer.json snippet shows how to lock the WordPress/php-toolkit dependency to a specific commit hash or tag, ensuring a precise version of the library is used.

```json
{
	"require": {
		"WordPress/php-toolkit": "dev-trunk#122b547"
	}
}
```

--------------------------------

### Compute Character-Based Diff in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Merge/vendor-patched/yetanotherape/diff-match-patch/README.md

Compares two plain texts and returns an array of differences. This example demonstrates a basic character-based diff, which can be tuned for word or line-based comparisons.

```php
<?php

use DiffMatchPatch\DiffMatchPatch;

$text1 = "The quick brown fox jumps over the lazy dog.";
$text2 = "That quick brown fox jumped over a lazy dog.";
$dmp = new DiffMatchPatch();
$diffs = $dmp->diff_main($text1, $text2, false);
var_dump($diffs);
```

```php
array(
    array(DiffMatchPatch::DIFF_EQUAL, "Th"),
    array(DiffMatchPatch::DIFF_DELETE, "e"),
    array(DiffMatchPatch::DIFF_INSERT, "at"),
    array(DiffMatchPatch::DIFF_EQUAL, " quick brown fox jump"),
    array(DiffMatchPatch::DIFF_DELETE, "s"),
    array(DiffMatchPatch::DIFF_INSERT, "ed"),
    array(DiffMatchPatch::DIFF_EQUAL, " over "),
    array(DiffMatchPatch::DIFF_DELETE, "the"),
    array(DiffMatchPatch::DIFF_INSERT, "a"),
    array(DiffMatchPatch::DIFF_EQUAL, " lazy dog."),
)
```

--------------------------------

### Implement PSR-3 Logger Interface in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/vendor-patched/log/README.md

This PHP example demonstrates how to use the `LoggerInterface` in a class constructor for dependency injection. It shows logging informational messages and handling exceptions by logging errors with contextual data, adhering to the PSR-3 specification.

```php
<?php

use Psr\Log\LoggerInterface;

class Foo
{
    private $logger;

    public function __construct(LoggerInterface $logger = null)
    {
        $this->logger = $logger;
    }

    public function doSomething()
    {
        if ($this->logger) {
            $this->logger->info('Doing work');
        }
           
        try {
            $this->doSomethingElse();
        } catch (Exception $exception) {
            $this->logger->error('Oh no!', array('exception' => $exception));
        }

        // do something useful
    }
}
```

--------------------------------

### Example Twig Template with Front Matter Comments

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This Twig template demonstrates how front matter can be embedded within Twig comments. The `FrontMatterLoader` processes these comments to extract metadata.

```twig
{#---
title: Hello world
menu: main
weight: 20
---#}
{% extend layout.html.twig %}
{% block content %}
Hello world!
{% endblock %}
```

--------------------------------

### Apply Text Patches in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Merge/vendor-patched/yetanotherape/diff-match-patch/README.md

Applies a list of patches, generated in a Unidiff-like format, onto a plain text. The library attempts to apply patches even if the underlying text doesn't perfectly match. This example demonstrates generating patches and then applying them to a modified text.

```php
<?php

use DiffMatchPatch\DiffMatchPatch;

$dmp = new DiffMatchPatch();
$patches = $dmp->patch_make("The quick brown fox jumps over the lazy dog.", "That quick brown fox jumped over a lazy dog.");
// @@ -1,11 +1,12 @@
//  Th
// -e
// +at
//   quick b
// @@ -22,18 +22,17 @@
//  jump
// -s
// +ed
//   over
// -the
// +a
//   laz
$result = $dmp->patch_apply($patches, "The quick red rabbit jumps over the tired tiger.");
var_dump($result);
```

```php
array(
    "That quick red rabbit jumped over a tired tiger.",
    array (
        true,
        true,
    ),
);
```

--------------------------------

### Using Dot Access Data as an Array in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/dflydev/dot-access-data/README.md

This snippet demonstrates that the Data object implements the ArrayAccess interface, allowing it to be used with array-like syntax for getting, setting, and unsetting values. It highlights the equivalence between dot notation methods and array access.

```PHP
// Get
$data->get('name') === $data['name']; // true

$data['name'] = 'Dewey';
// is equivalent to
$data->set($name, 'Dewey');

isset($data['name']) === $data->has('name');

// Remove key
unset($data['name']);
```

--------------------------------

### URLSearchParams Member Methods

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/url/README.md

API documentation for the methods available on the `URLSearchParams` object for manipulating query parameters, including appending, deleting, getting, and setting values.

```APIDOC
URLSearchParams Class Members:
  void append(string $name, string $value)
    Appends a new name-value pair to the list.
  void delete(string $name[, string $value])
    Deletes all name-value pairs whose name is `$name` from the list. If the optional `$value` is provided, then only pairs with the same name and value are removed.
  string|null get(string $name)
    Returns the value of the first name-value pair whose name is `$name` in the list or null if there are no name-value pairs whose name is `$name` in the list.
  string[] getAll(string $name)
    Returns a list of values of all name-value pairs whose name is `$name`, in list order, or the empty list if there are no name-value pairs whose name is `$name` in the list.
  bool has(string $name[, string $value])
    Returns true if there is a name-value pair in the list, and false otherwise.
  void set(string $name, string $value)
    If the list contains name-value pairs whose name is `$name`, the first name-value pair in the list whose name is `$name` will have its value changed to `$value` and all others following it in the list will be removed. If the list does not contain a name-value pair whose name is `$name` then the new name-value pair will be appended to the list.
```

--------------------------------

### Using Slash as Path Delimiter in PHP Dot Access

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/dflydev/dot-access-data/README.md

This example illustrates that the DotAccessData library also supports forward slashes (/) as an alternative path delimiter, providing flexibility in how data paths are specified. It shows that both dot and slash notations yield the same result.

```PHP
$data->set('a/b/c', 'd');
echo $data->get('a/b/c'); // "d"

$data->get('a/b/c') === $data->get('a.b.c'); // true
```

--------------------------------

### Generating Schema from Class with `from()` in PHP (Pre-PHP 7.4)

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/nette/schema/readme.md

Illustrates how to generate a structure schema from a class definition using `Expect::from()`, mapping public properties to schema elements. This example uses docblock types for property definitions.

```php
class Config
{
	/** @var string */
	public $name;
	/** @var string|null */
	public $password;
	/** @var bool */
	public $admin = false;
}

$schema = Expect::from(new Config);

$data = [
	'name' => 'jeff',
];

$normalized = $processor->process($schema, $data);
// $normalized instanceof Config
// $normalized = {'name' => 'jeff', 'password' => null, 'admin' => false}
```

--------------------------------

### Check for Front Matter Existence in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This PHP example shows how to use the `exists` method of the `FrontMatter` class to determine if a given string contains front matter. It returns a boolean indicating its presence.

```php
<?php

$frontMatter = new \Webuni\FrontMatter\FrontMatter();

$hasFrontMatter = $frontMatter->exists($string);
```

--------------------------------

### Perform Fuzzy String Matching in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Merge/vendor-patched/yetanotherape/diff-match-patch/README.md

Finds the best fuzzy match of a search string within a plain text near a given location, weighted by accuracy and position. The example shows how to use `match_main` and adjust the `Match_Threshold`.

```php
<?php

use DiffMatchPatch\DiffMatchPatch;

$dmp = new DiffMatchPatch();
$text = "The quick brown fox jumps over the lazy fox.";
$pos = $dmp->match_main($text, "fox", 0); // Returns 16
$pos = $dmp->match_main($text, "fox", 40); // Returns 40
$pos = $dmp->match_main($text, "jmps"); // Returns 20
$pos = $dmp->match_main($text, "jmped"); // Returns -1
$pos = $dmp->Match_Threshold = 0.7;
$pos = $dmp->match_main($text, "jmped"); // Returns 20
```

--------------------------------

### PHP IDNA Overriding Default Options

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/idna/README.md

This example demonstrates how to selectively override the default IDNA options. It shows how to change the 'CheckHyphens' option and then use 'Idna::toAscii()' to process a domain, checking for specific errors like 'ERROR_TRAILING_HYPHEN'.

```php
use Rowbot\Idna\Idna;

$result = Idna::toAscii('x-.xn--nxa', ['CheckHyphens' => true]);
$result->hasErrors(); // true
$result->hasError(Idna::ERROR_TRAILING_HYPHEN); // true

$result = Idna::toAscii('x-.xn--nxa', ['CheckHyphens' => false]);
$result->hasErrors(); // false
$result->hasError(Idna::ERROR_TRAILING_HYPHEN); // false
```

--------------------------------

### Example Twig Template with Injected Front Matter Variables

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This snippet illustrates how a Twig template appears after `FrontMatterLoader` has processed and injected front matter data as `set` variables. This allows direct access to front matter values within the template.

```twig
{% set title = "Hello world" %}
{% set menu = "main" %}
{% set weight = 20 %}
{% line 5 %}
{% extend layout.html.twig %}
{% block content %}
Hello world!
{% endblock %}
```

--------------------------------

### Define Array and List Schemas with Expect::arrayOf() and Expect::listOf() in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/nette/schema/readme.md

Explains how to define schemas for arrays and lists using `Expect::arrayOf()` and `Expect::listOf()`. `Expect::arrayOf()` allows specifying element types and optionally key types, while `Expect::listOf()` enforces numerically indexed arrays. Examples show validation success and failure scenarios.

```php
$schema = Expect::arrayOf('string');

$processor->process($schema, ['hello', 'world']); // OK
$processor->process($schema, ['a' => 'hello', 'b' => 'world']); // OK
$processor->process($schema, ['key' => 123]); // ERROR: 123 is not a string
```

```php
$schema = Expect::arrayOf('string', 'int');

$processor->process($schema, ['hello', 'world']); // OK
$processor->process($schema, ['a' => 'hello']); // ERROR: 'a' is not int
```

```php
$schema = Expect::listOf('string');

$processor->process($schema, ['a', 'b']); // OK
$processor->process($schema, ['a', 123]); // ERROR: 123 is not a string
$processor->process($schema, ['key' => 'a']); // ERROR: is not a list
$processor->process($schema, [1 => 'a', 0 => 'b']); // ERROR: is not a list
```

```php
Expect::arrayOf(Expect::bool())
```

--------------------------------

### Run Tests with Composer

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/league/config/README.md

This command executes the test suite for the PHP configuration library using Composer, ensuring the codebase functions as expected.

```Bash
composer test
```

--------------------------------

### Run Blueprints v2 CLI Tool

Source: https://github.com/wordpress/php-toolkit/blob/trunk/README.md

Download the blueprints.phar file and execute it via PHP CLI to use the Blueprints v2 runner. Further arguments and options can be found by following the help message.

```sh
php blueprints.phar
```

--------------------------------

### Run CommonMark PHP Library Tests

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/league/commonmark/README.md

This command executes the test suite for the `league/commonmark` library, including tests against the latest supported CommonMark specification.

```bash
$ composer test
```

--------------------------------

### Run PHPUnit Test Suite

Source: https://github.com/wordpress/php-toolkit/blob/trunk/README.md

Execute the PHPUnit test suite for the PHP Toolkit project using Composer.

```sh
composer test
```

--------------------------------

### Run CommonMark PHP Library Performance Benchmarks

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/league/commonmark/README.md

This command runs the included benchmark tool to compare the performance of `league/commonmark` against other popular Markdown parsers.

```bash
$ ./tests/benchmark/benchmark.php
```

--------------------------------

### URLSearchParams Class Overview and Constructor

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/url/README.md

Introduction to the `URLSearchParams` object for working with query strings, including its constructor signature, supported initialization types, and potential exceptions.

```APIDOC
URLSearchParams Class:
  Description: The URLSearchParams object allows you to work with query strings when you don't need a full URL. The URLSearchParams object implements the `Iterator` interface so that you may iterate over the list of search parameters. The iterator will return an array containing exactly 2 items. The first item is the parameter name and the second item is the parameter value.

  Constructor:
    URLSearchParams([iterable<int|string, array<int|string, scalar|\Stringable>|(\Traversable<int|string, scalar|\Stringable>&\Countable)>|object|string|\Stringable $init])
    Throws:
      \Rowbot\URL\Exception\TypeError
        When an iterable is passed and one if its values is not iterable.
        When an iterable is passed and one of its values is not countable, such as an object that implements `\Iterator`, but not `\Countable`.
        When an iterable is passed and one of its sequences does not contain exactly 2 items, such as an array that contains only 1 string.
```

```php
use Rowbot\URL\URLSearchParams;

// Construct an empty list of search params.
$params = new URLSearchParams();

// Construct a new list from a query string. Remember that a leading "?" will be stripped.
$params = new URLSearchParams('?foo=bar');

// Construct a new list using an array of arrays containing strings. Alternatively, you could pass an
// object that implements the Traversable interface and whose iterator returns an array of arrays,
// with each array containing exactly 2 items.
$params = new URLSearchParams([
    ['foo', 'bar'],
    ['foo', 'bar'], // Duplicates are allowed!
    ['one', 'two']
]);

// Iterate over a URLSearchParams object.
foreach ($params as $index => $param) {
    if ($index > 0) {
        echo '&';
    }

    echo $param[0] . '=' . $param[1];
}

// Above loop prints "foo=bar&foo=bar&one=two".

// Construct a new list using an object
$obj = new \stdClass();
$obj->foo = 'bar';
$params = new URLSearchParams($obj);

// Copy an existing URLSearchParams object into a new one.
$params1 = new URLSearchParams($params);
```

--------------------------------

### Run PHP_CodeSniffer Linting Suite

Source: https://github.com/wordpress/php-toolkit/blob/trunk/README.md

Execute the PHP_CodeSniffer linting suite for the PHP Toolkit project using Composer to check for coding standard violations.

```sh
composer lint
```

--------------------------------

### Importing WordPress Content from a Bundled Blueprint

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

Demonstrates how to reference and import posts and pages from a bundled directory structure within a Blueprint using relative paths, showcasing the `content` property with `source` array pointing to HTML files.

```JSON
{
	"content": [
		{
			"type": "posts",
			"source": ["./wp-content/content/posts/posts/hello-world.html", "./wp-content/content/posts/pages/about-us.html"]
		}
	]
}
```

--------------------------------

### URL Class Constructor API Reference

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/url/README.md

Detailed API documentation for the `URL` class constructor. It specifies the parameters, their types, optional arguments like `logger`, and the `TypeError` exception thrown for invalid URL inputs during parsing.

```APIDOC
URL(string|\Stringable $url[, null|string|\Stringable $base = null, array $options = []])
  $url: The URL string or object to parse.
  $base: (Optional) The base URL for resolving relative URLs.
  $options: (Optional) An array of options.
    logger: An object implementing \Psr\Log\LoggerInterface for logging.

Throws:
  \Rowbot\URL\Exception\TypeError: When the URL parser determines that the given input is not a valid URL.
```

--------------------------------

### Encode UTF-8 String to Punycode in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/punycode/README.md

This PHP example demonstrates how to use the `Punycode::encode()` method to convert a UTF-8 encoded string into its Punycode ASCII representation. It includes a `try-catch` block to handle `PunycodeException` for robust error management.

```php
use Rowbot\Punycode\Punycode;

try {
    echo Punycode::encode('Hello-Another-Way-それぞれの場所'); // Hello-Another-Way--fc4qua05auwb3674vfr0b
} catch (\Rowbot\Punycode\Exception\PunycodeException $e) {
    echo 'An error occured!';
}
```

--------------------------------

### Decode Punycode String to UTF-8 in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/punycode/README.md

This PHP example demonstrates how to use the `Punycode::decode()` method to convert an ASCII Punycode string back into its original UTF-8 representation. It includes a `try-catch` block to handle `PunycodeException` for robust error management.

```php
use Rowbot\Punycode\Punycode;

try {
    echo Punycode::decode('Hello-Another-Way--fc4qua05auwb3674vfr0b'); // Hello-Another-Way-それぞれの場所
} catch (\Rowbot\Punycode\Exception\PunycodeException $e) {
    echo 'An error occured!';
}
```

--------------------------------

### Integrate Front Matter with League CommonMark in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This PHP snippet demonstrates how to extend the `league/commonmark` converter with the `FrontMatterLeagueCommonMarkExtension`. This allows Markdown files with front matter to be parsed, with the front matter being removed before HTML conversion.

```php
$frontMatter = new \Webuni\FrontMatter\FrontMatter();
$extension = new \Webuni\FrontMatter\Markdown\FrontMatterLeagueCommonMarkExtension($frontMatter);

$converter = new \League\CommonMark\CommonMarkConverter([]);
$converter->getEnvironment()->addExtension($extension);
$html = $converter->convertToHtml('markdown'); // html without front matter
```

--------------------------------

### WordPress Blueprint Runner Execution Plan and Error Handling

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Blueprints/Versions/Version2/json-schema/wsp/wsp-1-blueprint-v2-schema/proposal.md

Outlines the required steps for a Blueprint runner to execute a plan, covering remote asset resolution, sequential step execution, and mandatory error handling protocols to ensure reliable Blueprint processing.

```APIDOC
Blueprint Execution Plan Steps:
1. Remote assets resolution:
   - The Blueprint runner is free to schedule the download in any way it wants.
   - This WSP recommends using queue of n concurrent downloads, scheduling them in the order they will be needed to execute the Blueprint, and executing the plan in parallel.
   - Whenever the runner needs to run a step that depends on a remote asset, it MUST wait until that asset is available.
2. Step execution:
   - The runner MUST execute the steps in the order defined by the Execution Plan.
   - It MUST NOT parallelize step execution.
3. Error handling:
   - If a step fails, the runner MUST stop the execution of the Blueprint and report a meaningful error.
   - The runner MUST NOT stop if the failed step explicitly declares that it is optional.
   - A Blueprint that failed to execute MUST NOT clean up any resources.
   - The Execution Target remains available for the developer to debug and restore any backups.
```

--------------------------------

### PHP IDNA Default Configuration Options

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/idna/README.md

This snippet illustrates the default and strictest configuration options for the IDNA library. These options include various checks for hyphens, Bidi characters, joiners, and adherence to STD3 ASCII rules, along with a flag for transitional processing and DNS length verification.

```php
// Default options.
[
  'CheckHyphens'            => true,
  'CheckBidi'               => true,
  'CheckJoiners'            => true,
  'UseSTD3ASCIIRules'       => true,
  'Transitional_Processing' => false,
  'VerifyDnsLength'         => true, // Only for Idna::toAscii()
];
```

--------------------------------

### Diff-Match-Patch Library API Overview

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Merge/vendor-patched/yetanotherape/diff-match-patch/README.md

Overview of the Diff-Match-Patch library's consistent API across various programming languages. Regardless of the language, each library uses the same API and functionality.

```APIDOC
DiffMatchPatch Library API:
  - Consistent API across all supported languages.
  - Core functionalities: diff, match, patch.
  - Available in:
    - PHP
    - C++
    - C#
    - Dart
    - Java
    - JavaScript
    - Lua
    - Objective-C
    - Python
```

--------------------------------

### Convert Domain to ASCII and Handle Errors in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/idna/README.md

Demonstrates how to use the `Idna::toAscii` method to convert a domain name to its ASCII representation and check for errors. It's crucial to verify `hasErrors()` on the returned `IdnaResult` object before using the converted domain, as a domain with errors should not be used.

```php
use Rowbot\Idna\Idna;

$result = Idna::toAscii('x-.xn--nxa');

// You must not use an ASCII domain that has errors.
if ($result->hasErrors()) {
    throw new \Exception();
}

echo $result->getDomain(); // x-.xn--nxa
```

--------------------------------

### Regenerate Root Composer.json File

Source: https://github.com/wordpress/php-toolkit/blob/trunk/README.md

Run this script to regenerate the root composer.json file, which amalgamates dependencies and autoload rules from all component composer.json files.

```sh
bin/regenerate_composer.json.php
```

--------------------------------

### Bash Running PHPUnit Tests for IDNA Library

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/idna/README.md

This command executes the PHPUnit test suite for the IDNA library. It is recommended to run these tests after generating new Unicode data files to ensure the library functions correctly with the updated version.

```bash
vendor/bin/phpunit
```

--------------------------------

### Process data with a basic Nette Schema structure

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/nette/schema/readme.md

This PHP snippet demonstrates processing sample data against a previously defined schema, showing how valid data passes validation.

```PHP
$data = [
	'processRefund' => true,
	'refundAmount' => 17,
];

$normalized = $processor->process($schema, $data); // OK, it passes
```

--------------------------------

### Parse String with Front Matter in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/webuni/front-matter/README.md

This PHP snippet demonstrates how to initialize the `FrontMatter` parser and extract data and content from a string containing front matter. It shows how to access the parsed data and the remaining content.

```php
<?php

$frontMatter = new \Webuni\FrontMatter\FrontMatter();

$document = $frontMatter->parse($string);

$data = $document->getData();
$content = $document->getContent();
```

--------------------------------

### Idna::toAscii Method Reference

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/DataLiberation/vendor-patched/rowbot/idna/README.md

API documentation for the `Idna::toAscii` method, which converts a domain name to its ASCII form. This method returns an `IdnaResult` object, and the transformation is considered failed if any errors are recorded. It supports various options to customize behavior, including checks for bi-directional characters, hyphens, joiners, ASCII rules, transitional processing, and DNS length validation.

```APIDOC
Idna::toAscii(string $domain, array $options = []): IdnaResult
  Description: Converts a domain name to its ASCII form. Anytime an error is recorded while doing an ASCII transformation, the transformation is considered to have failed and whatever domain name string is returned is considered "garbage".
  Parameters:
    $domain: A domain name to convert to ASCII.
    $options: An array of options for customizing the behavior of the transformation. Possible options include:
      "CheckBidi": Checks the domain name string for errors with bi-directional characters. Defaults to true.
      "CheckHyphens": Checks the domain name string for the positioning of hypens. Defaults to true.
      "CheckJoiners": Checks the domain name string for errors with joining code points. Defaults to true.
      "UseSTD3ASCIIRules": Disallows the use of ASCII characters other than [a-zA-Z0-9-]. Defaults to true.
      "Transitional_Processing": Whether transitional or non-transitional processing is used. When enabled, processing behaves more like IDNA2003 and when disabled behaves like IDNA2008. Defaults to false, which means that non-transitional processing is used by default.
      "VerifyDnsLength": Validates the length of the domain name string and it's individual labels. Defaults to true.
  Returns: IdnaResult object.
```

--------------------------------

### Convert GitHub-Flavored Markdown to HTML using GithubFlavoredMarkdownConverter in PHP

Source: https://github.com/wordpress/php-toolkit/blob/trunk/components/Markdown/vendor-patched/league/commonmark/README.md

This PHP snippet illustrates how to use the `GithubFlavoredMarkdownConverter` class, a drop-in replacement for `CommonMarkConverter`, to convert GFM-formatted text to HTML. It also includes security-focused configuration options.

```php
use League\CommonMark\GithubFlavoredMarkdownConverter;

$converter = new GithubFlavoredMarkdownConverter([
    'html_input' => 'strip',
    'allow_unsafe_links' => false,
]);

echo $converter->convert('# Hello World!');

// <h1>Hello World!</h1>
```