### Add a simple BBCode from example

Source: https://github.com/s9e/textformatter/wiki/Plugins:-BBCodes

Demonstrates how to add a basic BBCode tag like [b] to the formatter using a predefined example. This is the easiest way to get started with custom BBCodes.

```php
<?php
include 's9e/TextFormatter.php';

$cb = new ConfigBuilder;

$cb->addBBCodeFromExample(
	'[b]{TEXT}[/b]',
	'<b>{TEXT}</b>'
);
```

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

### Install s9e\TextFormatter using Composer

Source: https://github.com/s9e/textformatter/blob/master/README.md

Install the library using Composer. This is the recommended method for installation.

```bash
composer require s9e/text-formatter
```

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

### Customize an Existing Bundle

Source: https://github.com/s9e/textformatter/blob/master/docs/Bundles/Your_own_bundle.md

Use an existing bundle's configurator as a starting point for your own. This example customizes the 'Forum' bundle by allowing 'b', 'i', and 'u' HTML elements.

```php
// Use the Forum bundle's configurator
$configurator = s9e\TextFormatter\Configurator\Bundles\Forum::getConfigurator();

// Customize it to your need
$configurator->HTMLElements->allowElement('b');
$configurator->HTMLElements->allowElement('i');
$configurator->HTMLElements->allowElement('u');

// Save it back as your own
$configurator->saveBundle('MyBundle', '/tmp/MyBundle.php');
```

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

### Accessing Template Parameters During Configuration and Rendering

Source: https://github.com/s9e/textformatter/blob/master/docs/Templating/Template_parameters.md

Shows how to retrieve all defined and used template parameters during configuration using getAllParameters() and how to get and set parameters during rendering using getParameter() and setParameter(). The example uses a BBCode '[noguests]' which depends on the '$S_LOGGED_IN' parameter.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->BBCodes->addCustom(
	'[noguests]{TEXT}[/noguests]',
	'<xsl:if test="$S_LOGGED_IN=1">{TEXT}</xsl:if>'
);

// Get a list of all parameters during configuration
echo "During configuration\n--------------------\n";
print_r($configurator->rendering->getAllParameters());
echo "\n";

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'Are you are logged in? [noguests]Yes you are.[/noguests]';
$xml  = $parser->parse($text);

echo "\nDuring rendering\n----------------\n";

// First with no value
echo 'Result with S_LOGGED_IN=', $renderer->getParameter('S_LOGGED_IN'), "\n";
echo $renderer->render($xml), "\n\n";

// Then with a value
$renderer->setParameter('S_LOGGED_IN', true);
echo 'Result with S_LOGGED_IN=', $renderer->getParameter('S_LOGGED_IN'), "\n";
echo $renderer->render($xml);
```

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

### Capture Spotify URIs with Preg and MediaEmbed

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Preg/Practical_examples.md

This example demonstrates how to use the Preg plugin to capture Spotify URIs and integrate them with the MediaEmbed plugin to generate an embeddable HTML player. It requires the MediaEmbed plugin to be installed and configured.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->MediaEmbed->add('spotify');
$configurator->Preg->match('/spotify:(?<id>\S+)/', 'SPOTIFY');

extract($configurator->finalize());

$text = 'spotify:user:erebore:playlist:788MOXyTfcUb1tdw4oC7KJ';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
<iframe data-s9e-mediaembed="spotify" allow="encrypted-media" allowfullscreen="" loading="lazy" scrolling="no" src="https://open.spotify.com/embed/user/erebore/playlist/788MOXyTfcUb1tdw4oC7KJ" style="border:0;border-radius:12px;height:380px;max-width:900px;width:100%"></iframe>
```

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

### BBCode Template Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/BBCodes/Custom_BBCode_syntax.md

A basic example of a BBCode tag used with a corresponding template, showing how tokens are replaced.

```html
[link destination={URL;useContent}]{TEXT}[/link]

<a href="{URL}">{TEXT}</a>
```

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

### Basic MediaEmbed Configuration and Usage

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Synopsis.md

Demonstrates how to configure the MediaEmbed plugin to support specific sites (Facebook, YouTube) and then parse and render example media URLs.

```php
$configurator = new s9e\TextFormatter\Configurator;

// We want to create an individual BBCode for [youtube] in
// addition to the default [media] BBCode
$configurator->BBCodes->add(
	'youtube',
	['defaultAttribute' => 'url', 'contentAttributes' => ['url']]
);

// Add the sites we want to support
$configurator->MediaEmbed->add('facebook');
$configurator->MediaEmbed->add('youtube');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$examples = [
	'[media]https://youtu.be/-cEzsCAzTak[/media]',
	'https://www.facebook.com/video/video.php?v=10100658170103643'
];

foreach ($examples as $text)
{
	$xml  = $parser->parse($text);
	$html = $renderer->render($xml);

	echo $html, "\n";
}
```

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

### Simple Pipe Table

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/PipeTables/Syntax.md

A basic example of a pipe table with headers, separators, and cells.

```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
```

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

### Horizontal Rule Syntax Examples

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Litedown/Syntax.md

Provides examples of Markdown syntax that render as horizontal rules.

```text
* * *

***

*****

- - -

---------------------------------------
```

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

### Configure FirstAvailable Minifier Strategy

Source: https://github.com/s9e/textformatter/blob/master/docs/JavaScript/Minifiers.md

Sets up the FirstAvailable minifier strategy, which attempts minification with multiple providers in order until one succeeds. This example prioritizes ClosureCompilerService, then MatthiasMullieMinify, with Noop as a fallback.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->enableJavaScript();

$minifier = $configurator->javascript->setMinifier('FirstAvailable');
$minifier->add('ClosureCompilerService');
$minifier->add('MatthiasMullieMinify');
$minifier->add('Noop');
```

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

### Minimal Bundle Configurator for Redistribution

Source: https://github.com/s9e/textformatter/blob/master/docs/Bundles/Your_own_bundle.md

A minimal example of a bundle configurator extending `s9e\TextFormatter\Configurator\Bundle`. It configures plugins and sets up a native PHP renderer, preparing the bundle for redistribution.

```php
namespace My\Project\TextFormatter;

use s9e\TextFormatter\Configurator;
use s9e\TextFormatter\Configurator\Bundle as AbstractBundleConfigurator;

class BundleConfigurator extends AbstractBundleConfigurator
{
	public function configure(Configurator $configurator): void
	{
		// Configure plugins
		$configurator->BBCodes->addFromRepository('B');

		// Configure the PHP renderer to exist in the current namespace
		$configurator->rendering->engine            = 'PHP';
		$configurator->rendering->engine->className = __NAMESPACE__ . '\\Renderer';
		$configurator->rendering->engine->filepath  = __DIR__ . '/Renderer.php';
	}

	public static function saveBundle(): bool
	{
		$configurator = (new static)->getConfigurator();

		return $configurator->saveBundle(
			__NAMESPACE__ . '\\Bundle',
			__DIR__ . '/Bundle.php',
			['autoInclude' => false]
		);
	}
}
```

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

### Image HTML Output

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Litedown/Syntax.md

Displays the HTML output for the different image syntax examples.

```html
<p><img src="http://example.org/img.png" alt="">
<img src="http://example.org/img.png" alt="Alt text">
<img src="http://example.org/img.png" alt="Alt text" title="Image title">
<a href="http://example.org/"><img src="http://example.org/img.png" alt="Alt text"></a></p>
```

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

### Add Custom Host to PeerTube Media Embed

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Federated_sites.md

Use the PeerTubeHelper to add a custom instance for embedding PeerTube videos. This example adds 'neat.tube'.

```php
$configurator = new s9e\TextFormatter\Configurator;

// Use the PeerTube helper to add 'neat.tube' as a supported instance
$peertubeHelper = $configurator->MediaEmbed->getSiteHelper('peertube');
$peertubeHelper->addHost('neat.tube');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'https://neat.tube/w/3PWC7CoQnqfZ4AkupAcVGB';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Example HTML Comment

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/HTMLComments/Synopsis.md

Shows the expected output for a simple HTML comment after processing.

```html
<!-- comment -->
```

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

### Output of URL Whitelist Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Filters/URL_features/Whitelist_hosts.md

The HTML output generated after applying the URL restrictions to the input text.

```html
<a href="http://example.com">http://example.com</a>
http://notexample.org
<a href="http://www.example.org">http://www.example.org</a>
```

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

### Disallow Hosts Containing a Pattern

Source: https://github.com/s9e/textformatter/blob/master/docs/Filters/URL_features/Blacklist_hosts.md

Use `disallowHost()` with wildcards to prevent links to any host containing a specific pattern. This example demonstrates disallowing hosts with 'example' in their name.

```php
$configurator = new s9e\TextFormatter\Configurator;

$configurator->urlConfig->disallowHost('*example*');

// Test the URL config with the Autolink plugin
$configurator->Autolink;

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = implode("\n", ['http://example.org', 'http://notexample.org', 'http://www.example.org']);
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
http://example.org
http://notexample.org
http://www.example.org
```

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

### Emphasis HTML Output

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Litedown/Syntax.md

Shows the HTML output for the emphasis examples.

```html
<p>un<em>frigging</em>believable</p>

<p><strong><em>ON SALE!</em></strong></p>

<p>a * b = b * a</p>

<p>perform_complicated_task()</p>
```

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

### Output of Image Host Restriction Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Filters/URL_features/Whitelist_hosts.md

The HTML output demonstrating that only images from allowed hosts are rendered, while others and regular links are preserved as is.

```html
<img src="http://i.imgur.com/EMD4m1Q.png">
[img=http://notimgur.example.org/EMD4m1Q.png /]
<a href="http://example.org">http://example.org</a>
```

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

### Add Custom Host to XenForo Media Embed

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Federated_sites.md

Use the XenForoHelper to authorize embedding content from a specific XenForo domain. This example adds 'xenforo.com'.

```php
$configurator = new s9e\TextFormatter\Configurator;

// Use the XenForo helper to add 'xenforo.com' as an authorized source
$xenforoHelper = $configurator->MediaEmbed->getSiteHelper('xenforo');
$xenforoHelper->addHost('xenforo.com');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'https://xenforo.com/community/threads/embed-your-content-anywhere.217381/';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Rendered HTML for MediaEmbed Examples

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Synopsis.md

The resulting HTML output after parsing and rendering the media URLs using the MediaEmbed plugin.

```html
<span data-s9e-mediaembed="youtube" style="display:inline-block;width:100%;max-width:640px"><span style="display:block;overflow:hidden;position:relative;padding-bottom:56.25%"><iframe allow="clipboard-write" allowfullscreen="" loading="lazy" referrerpolicy="origin" scrolling="no" style="background:url(https://i.ytimg.com/vi/-cEzsCAzTak/hqdefault.jpg) 50% 50% / cover;border:0;height:100%;left:0;position:absolute;width:100%" src="https://www.youtube.com/embed/-cEzsCAzTak"></iframe></span></span>
<iframe data-s9e-mediaembed="facebook" allowfullscreen="" loading="lazy" onload="let c=new MessageChannel;c.port1.onmessage=e=&gt;this.style.height=e.data+'px';this.contentWindow.postMessage('s9e:init','*',[c.port2])" scrolling="no" style="border:0;height:360px;max-width:640px;width:100%" src="https://s9e.github.io/iframe/2/facebook.min.html#v10100658170103643"></iframe>
```

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

### Enable and Set Closure Compiler Application Minifier (npx)

Source: https://github.com/s9e/textformatter/blob/master/docs/JavaScript/Minifiers.md

Enables JavaScript minification and configures the Google Closure Compiler application using npx. Requires npx or a native executable to be installed.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->enableJavaScript();

// You can use npx or a native executable
$configurator->javascript->setMinifier(
	'ClosureCompilerApplication',
	'npx google-closure-compiler'
);
```

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

### Add Custom Host to Mastodon Media Embed

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Federated_sites.md

Use the MastodonHelper to add an additional supported instance for embedding Mastodon toots. This example adds 'infosec.exchange'.

```php
$configurator = new s9e\TextFormatter\Configurator;

// Use the Mastodon helper to add 'infosec.exchange' as a supported instance
$mastodonHelper = $configurator->MediaEmbed->getSiteHelper('mastodon');
$mastodonHelper->addHost('infosec.exchange');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'https://infosec.exchange/@SwiftOnSecurity/109579438603578302';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Customizing Autovideo File Extensions

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Autovideo/Synopsis.md

Shows how to change the list of recognized video file extensions for the Autovideo plugin. This example uses '.mkv' as a custom extension.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->Autovideo->fileExtensions = ['mp4', 'mkv'];

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'http://example.org/video.mkv';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
<video controls="" src="http://example.org/video.mkv"></video>
```

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

### Parse Plain Text to XML

Source: https://github.com/s9e/textformatter/blob/master/docs/Internals/Storage_format.md

Demonstrates parsing a simple string with no markup into its XML representation using the Forum bundle. The output XML is guaranteed to start with '<t>'.

```php
use s9e\TextFormatter\Bundles\Forum as TextFormatter;

$text = 'Plain & boring text.';
$xml  = TextFormatter::parse($text);

echo $xml;
```

```xml
<t>Plain &amp; boring text.</t>
```

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

### Enable and Set Closure Compiler Application Minifier (Java)

Source: https://github.com/s9e/textformatter/blob/master/docs/JavaScript/Minifiers.md

Enables JavaScript minification and configures the Google Closure Compiler application using its Java executable. Requires PHP's exec() and the Java application to be installed.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->enableJavaScript();

// Using the Java application
$configurator->javascript->setMinifier(
	'ClosureCompilerApplication',
	'java -jar /usr/local/bin/compiler.jar'
);
```

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

### Basic Task List Rendering

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/TaskLists/Synopsis.md

Demonstrates how to initialize the Task Lists plugin and render a text containing task items into HTML.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->Litedown;
$configurator->TaskLists;

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = "- [x] checked\n" +
      "- [X] Checked\n" +
      "- [ ] unchecked";
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Load and Use FancyPants Plugin

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/FancyPants/Synopsis.md

Demonstrates how to load the FancyPants plugin and use the parser and renderer to convert text with fancy symbols.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->plugins->load('FancyPants');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'Fancy "quotes", symbols (c)(tm), dashes -- and elipsis...';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Create and Save a New Bundle

Source: https://github.com/s9e/textformatter/blob/master/docs/Bundles/Your_own_bundle.md

Configure plugins and settings, then save the bundle to a file. This snippet shows adding BBCodes and Emoticons, then saving the bundle as 'MyBundle.php'.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->BBCodes->addFromRepository('B');
$configurator->BBCodes->addFromRepository('I');
$configurator->BBCodes->addFromRepository('URL');
$configurator->Emoticons->add(':)', '/path/to/img.png');

$success = $configurator->saveBundle('MyBundle', '/tmp/MyBundle.php');
var_dump($success);
```

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

### Indented Code Block Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Litedown/Syntax.md

An example of an indented code block in Markdown, which is preceded by an empty line and indented with spaces or tabs.

```text
Check out this program:

    10 PRINT "Hello"
	20 GOTO 10
```

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

### Add BBCodes from Repository

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/BBCodes/Synopsis.md

Demonstrates how to add predefined BBCodes like 'B' and 'URL' from the bundled repository. This is a quick way to enable common BBCodes.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->BBCodes->addFromRepository('B');
$configurator->BBCodes->addFromRepository('URL');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'Here be [url=http://example.org]the [b]bold[/b] URL[/url].';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
Here be <a href="http://example.org">the <b>bold</b> URL</a>.
```

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

### Filter Order Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Filters/Tag_filters.md

This example illustrates the effect of filter order on attribute validation. A filter prepended to the chain modifies an attribute before validation, causing it to be invalidated. A filter appended after validation does not cause invalidation.

```php
function setTagAttribute($tag, $attrName, $attrValue)
{
	$tag->setAttribute($attrName, $attrValue);
}

$configurator = new s9e\TextFormatter\Configurator;

$configurator->BBCodes->addCustom('[test x={NUMBER1?} y={NUMBER2?}]', '');

// Add our custom filters to this tag
$configurator->tags['test']->filterChain->prepend('setTagAttribute($tag, "x", "potato")');
$configurator->tags['test']->filterChain->append ('setTagAttribute($tag, "y", "potato")');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = '[test x=1 y=2]';
$xml  = $parser->parse($text);

echo $xml;
```

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

### Add Keywords and Render Links

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Keywords/Synopsis.md

Demonstrates how to add keywords, set a custom template for rendering them as links, and then parse and render text. Keywords are case-sensitive by default.

```php
$configurator = new s9e\TextFormatter\Configurator;

// Add a couple of keywords
$configurator->Keywords->add('Bulbasaur');
$configurator->Keywords->add('Pikachu');

// Keywords are case-sensitive by default but you can make case-insensitive.
// This is not recommended if the list of keywords contain words that could
// appear in normal speech, e.g. "Fire", "Air", "The"
$configurator->Keywords->caseSensitive = false;

// Set the template that renders them
$configurator->Keywords->getTag()->template
	= '<a href="http://bulbapedia.bulbagarden.net/wiki/{@value}"><xsl:apply-templates/></a>';

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'Bulbasaur and Pikachu';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Load and Use Autoemail Plugin

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Autoemail/Synopsis.md

Demonstrates how to load the Autoemail plugin and use the parser and renderer to convert an email address into a mailto link.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->plugins->load('Autoemail');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'Email me at user@example.org';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
Email me at <a href="mailto:user@example.org">user@example.org</a>
```

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

### Allowed XSL Variable Declaration

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

An example of an allowed XSL variable declaration.

```XML
<b>...</b>
```

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

### Allowed Script Tag

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

An example of an allowed script tag, typically for non-executable content.

```HTML
<script>echo "sup";</script>
```

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

### Basic PipeTables Usage

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/PipeTables/Synopsis.md

Demonstrates how to load the PipeTables plugin and parse a simple text table into HTML. Requires the s9e/textformatter library.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->plugins->load('PipeTables');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'a | b' . "\n"
      . '--|--' . "\n"
      . 'c | d';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
<table><thead><tr><th>a</th><th>b</th></tr></thead>
<tbody><tr><td>c</td><td>d</td></tr></tbody></table>
```

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

### Basic Litedown Parsing

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Litedown/Synopsis.md

Demonstrates how to load the Litedown plugin and parse a simple Markdown-like link into HTML.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->plugins->load('Litedown');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = '[Link text](http://example.org)';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
<p><a href="http://example.org">Link text</a></p>
```

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

### Allowed Dynamic JavaScript

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Examples of allowed dynamic JavaScript, where values are safely constrained to numbers.

```HTML
<script>.important { alert(1) }</script>
```

```HTML
<b onclick="alert(1)">...</b>
```

```HTML
<b onclick="alert({@foo})">...</b>
```

```XML
<b><xsl:copy-of select="@onclick"/>...</b>
```

```XML
<b><xsl:attribute name="onclick"><xsl:value-of select="@foo"/></xsl:attribute>...</b>
```

```HTML
<b onclick="this.style.width={0+@foo}">...</b>
```

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

### Parse and Render with Forum Bundle (BBCodes)

Source: https://github.com/s9e/textformatter/blob/master/docs/Getting_started/Using_predefined_bundles.md

Demonstrates parsing BBCode-formatted text and rendering it to HTML using the Forum bundle. Includes an assertion to verify the unparsing functionality.

```php
use s9e\TextFormatter\Bundles\Forum as TextFormatter;

$text = 'To-do list:
[list]
  [*] Say hello to the world :)
  [*] Go to http://example.com
  [*] Try to trip the parser with [b]mis[i]nes[/b]ted[u] tags[/i][/u]
  [*] Watch this video: [media]http://www.youtube.com/watch?v=QH2-TGUlwu4[/media]
[/list]';

// Parse the original text
$xml = TextFormatter::parse($text);

// Here you should save $xml to your database
// $db->query('INSERT INTO ...');

// Render and output the HTML result
echo TextFormatter::render($xml);

// You can "unparse" the XML to get the original text back
assert(TextFormatter::unparse($xml) === $text);
```

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

### Manually Configure a Custom Site for MediaEmbed

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Synopsis.md

Shows how to manually add a custom site configuration for YouTube, defining its host, extraction regex, and iframe source.

```php
$configurator = new s9e\TextFormatter\Configurator;

$configurator->MediaEmbed->add(
	'youtube',
	[
		'host'    => 'youtube.com',
		'extract' => "!youtube\.com/watch\?v=(?'id'[-\\w]+)!",
		'iframe'  => [
			'width'  => 560,
			'height' => 315,
			'src'    => 'http://www.youtube.com/embed/{@id}'
		]
	]
);

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'http://www.youtube.com/watch?v=-cEzsCAzTak';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Allowed Dynamic CSS

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Examples of allowed dynamic CSS, where values are safely constrained or known.

```HTML
<style>.important { color:red }</style>
```

```HTML
<b style="color:red">...</b>
```

```HTML
<b style="color:{@foo}">...</b>
```

```XML
<b><xsl:copy-of select="@style"/>...</b>
```

```XML
<b><xsl:attribute name="style"><xsl:value-of select="@foo"/></xsl:attribute>...</b>
```

```HTML
<b style="width:{0+@foo}px">...</b>
```

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

### Add and Configure Tag Rules

Source: https://github.com/s9e/textformatter/blob/master/docs/Rules/Tag_rules.md

Demonstrates adding a tag and configuring its rules using autoReopen and denyChild.

```php
$configurator = new Configurator;

$tag = $configurator->tags->add('B');
$tag->rules->autoReopen();
$tag->rules->denyChild('X');
```

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

### Rendered HTML Output

Source: https://github.com/s9e/textformatter/blob/master/docs/Bundles/Forum.md

The HTML output generated from the basic forum text parsing example.

```html
<blockquote><div><cite>John Doe wrote:</cite>Star Wars spoiler: <details class="spoiler"><summary class="spoiler-header" data-hide="Hide" data-show="Show">Spoiler </summary><div class="spoiler-content">Snapes kills Dumbledore</div></details></div></blockquote>
```

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

### Parse and Render with Fatdown Bundle (Markdown)

Source: https://github.com/s9e/textformatter/blob/master/docs/Getting_started/Using_predefined_bundles.md

Demonstrates parsing Markdown-formatted text and rendering it to HTML using the Fatdown bundle. Includes an assertion to verify the unparsing functionality.

```php
use s9e\TextFormatter\Bundles\Fatdown as TextFormatter;

$text = 'To-do list:

  * Say hello to the world :)
  * Go to http://example.com
  * Try to trip the parser with **mis*nes**ted<u> tags*
  * Watch this video: http://www.youtube.com/watch?v=QH2-TGUlwu4';

// Parse the original text
$xml = TextFormatter::parse($text);

// Here you should save $xml to your database
// $db->query('INSERT INTO ...');

// Render and output the HTML result
echo TextFormatter::render($xml);

// You can "unparse" the XML to get the original text back
assert(TextFormatter::unparse($xml) === $text);
```

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

### Use Multiple Keyword Lists with Different Tags

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Keywords/Synopsis.md

Demonstrates how to manage multiple distinct lists of keywords, mapping each list to a different tag name (e.g., COLOR, SNACK) by renaming the plugin instance.

```php
$configurator = new s9e\TextFormatter\Configurator;

$configurator->plugins->load('Keywords', ['tagName' => 'COLOR']);
$configurator->Colors = $configurator->Keywords;
unset($configurator->Keywords);

$configurator->plugins->load('Keywords', ['tagName' => 'SNACK']);
$configurator->Snacks = $configurator->Keywords;
unset($configurator->Keywords);

$configurator->Colors->add('blue');
$configurator->Colors->add('red');

$configurator->Snacks->add('Mars');
$configurator->Snacks->add('Twix');

extract($configurator->finalize());

$text = "blue red\nMars Twix";
$xml  = $parser->parse($text);

echo $xml;
```

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

### Allowed XPath Expressions

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Examples of XPath expressions that are permitted, including simple attribute access and string literals.

```XSLT
<b title="document()"/>
```

```XSLT
<b title="{&quot;document()&quot;}"/>
```

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

### Allow Child Tag Rule

Source: https://github.com/s9e/textformatter/blob/master/docs/Rules/Tag_rules.md

Example of allowing a specific tag ('X') to be used as a child of the current tag.

```php
$tag->rules->allowChild('X');
```

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

### SUP BBCode and XSL

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/BBCodes/Add_from_the_repository.md

Demonstrates the BBCode for superscript text and its HTML equivalent.

```bbcode
[SUP]{TEXT}[/SUP]
```

```html
<sup>{TEXT}</sup>
```

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

### BBCode with Multiple Tokens in Template

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/BBCodes/Custom_BBCode_syntax.md

An example of a BBCode tag with multiple attributes and a template that uses these attributes and tokens.

```html
[box color={COLOR} width={NUMBER} height={NUMBER}]{TEXT}[/box]

<div style="color: {COLOR}; width: {@width}px; height: {@height}px">{TEXT}</div>
```

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

### Compact Pipe Table

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/PipeTables/Syntax.md

Demonstrates a compact pipe table syntax where outer pipes and spaces are optional.

```markdown
Header 1|Header 2
-|- 
Cell 1|Cell 2
```

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

### Disallowing Unsupported XSL Elements

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Shows examples of disallowed XSL elements and attributes that are considered unsupported or potentially unsafe.

```XSLT
<xsl:message>..</xsl:message>
```

```XSLT
<xsl:apply-templates mode="unsupported"/>
```

```XSLT
<xsl:copy-of/>
```

```XSLT
<xsl:if/>
```

```XSLT
<xsl:value-of/>
```

```XSLT
<xsl:variable/>
```

```XSLT
<xsl:when/>
```

```XSLT
<xsl:value-of select="foo('bar')"/>
```

```XSLT
<hr title="{foo()}"/>
```

```XSLT
<xsl:element name="{foo(@name)}"/>
```

```XSLT
<xsl:element name="x div"/>
```

```XSLT
<xsl:element/>
```

```XSLT
<b><xsl:attribute name="data foo"/></b>
```

```XSLT
<b><xsl:attribute name="12foo"/></b>
```

```XSLT
<xsl:attribute/>
```

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

### Subscript and Superscript Syntax

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Litedown/Syntax.md

Demonstrates the syntax for subscript (using ~) and superscript (using ^) formatting.

```markdown
x^2
x^2^
x^(n - 1)
x^(n^2)
x^(n^(2))
H~2~O
H~(2)O
```

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

### Allowed Dynamic URL

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Examples of allowed dynamic URLs, including those that are safely prefixed or are known to be valid URL schemes.

```HTML
<a href="http://example.org">...</a>
```

```HTML
<a href="{@foo}">...</a>
```

```HTML
<a href="http://{@foo}">...</a>
```

```HTML
<a href="//{@foo}">...</a>
```

```HTML
<a href="user/{@foo}">...</a>
```

```HTML
<a href="#{@foo}">...</a>
```

```HTML
<a href="foo#{@foo}">...</a>
```

```HTML
<a href="foo?{@foo}">...</a>
```

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

### Allow Descendant Tag Rule

Source: https://github.com/s9e/textformatter/blob/master/docs/Rules/Tag_rules.md

Example of allowing a specific tag ('X') to be used as a non-child descendant of the current tag.

```php
$tag->rules->allowDescendant('X');
```

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

### BBCode with Options

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/BBCodes/Custom_BBCode_syntax.md

Demonstrates setting BBCode options like 'forceLookahead' and 'tagName' directly in the opening tag. Boolean values are set to 'true' or 'false'.

```plaintext
[B $forceLookahead=true]{TEXT}[/B]
[* $tagName=LI]{TEXT}[/*]
```

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

### Rendered HTML for Safe Elements Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/HTMLElements/Synopsis.md

The resulting HTML after parsing and rendering the text with allowed safe elements and attributes.

```html
<b>Bold</b> and <i>italic</i> are allowed, but only <b class="important">bold</b> can use the "class" attribute, not <i>italic</i>.
```

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

### Allowed XSL Elements and Attributes

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Examples of XSL elements and attributes that are permitted, often requiring specific conditions or valid syntax.

```XSLT
<b>...</b>
```

```XSLT
<xsl:apply-templates/>
```

```XSLT
<xsl:copy-of select="@foo"/>
```

```XSLT
<xsl:if test="@foo"/>
```

```XSLT
<xsl:value-of select="@foo"/>
```

```XSLT
<xsl:variable name="foo"/>
```

```XSLT
<xsl:when test="@foo"/>
```

```XSLT
<xsl:value-of select="substring-after('foo()', &quot;bar()&quot;)"/>
```

```XSLT
<xsl:value-of select="1-number(@foo)"/>
```

```XSLT
<xsl:element name="{string(@name)}"/>
```

```XSLT
<xsl:element name="x-div"/>
```

```XSLT
<xsl:element name="x:div"/>
```

```XSLT
<b><xsl:attribute name="data-123foo"/></b>
```

```XSLT
<b><xsl:attribute name="{@name}"/></b>
```

```XSLT
<xsl:if test="foo and (bar or (baz mod (1 + 1)))"/>
```

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

### Parse Text to XML with Parser

Source: https://github.com/s9e/textformatter/wiki/Basic-usage

Instantiate the Parser with the configuration array obtained from ConfigBuilder. The parse method transforms plain text into an XML string.

```php
<?php
use s9e\TextFormatter\Parser;

include 's9e/TextFormatter/src/Parser.php';

// Create an instance of Parser, use the config from earlier
$parser = new Parser($parserConfig);

// Parse the text, it will return a string containing XML
$xml = $parser->parse(
	'Hello [b]bold[/b] [highlight=#ffff00]sunny[/highlight] world! :)'
);

```

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

### XSLT: Normalized IF/ENDIF Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Templating/Template_normalization/Extend.md

This is the resulting XSLT output after the PHP normalization process, demonstrating the replacement of custom comments with an <xsl:if> element.

```xslt
<xsl:if test="$S_USER_LOGGED_IN"><div>Welcome!</div></xsl:if>
```

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

### Configure Flash Full Screen Check

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Demonstrates configuring the DisallowFlashFullScreen check with boolean parameters.

```XML
DisallowFlashFullScreen(true) allows <embed allowFullScreen="true" src="http://example.com/example.swf"/>
```

```XML
DisallowFlashFullScreen(false) disallows <embed allowFullScreen="true" src="http://example.com/example.swf"/>
```

```XML
DisallowFlashFullScreen(true) disallows <embed allowFullScreen="true" src="{@url}"/>
```

```XML
DisallowFlashFullScreen(true) disallows <embed allowFullScreen="true"><xsl:copy-of select="@src"/></embed>
```

```XML
DisallowFlashFullScreen(true) allows <object><param name="allowFullScreen" value="true"/><param name="movie" value="http://example.com/example.swf"/></object>
```

```XML
DisallowFlashFullScreen(false) disallows <object><param name="allowFullScreen" value="true"/><param name="movie" value="http://example.com/example.swf"/></object>
```

```XML
DisallowFlashFullScreen(true) disallows <object><param name="allowFullScreen" value="true"/><param name="movie" value="{@url}"/></object>
```

```XML
DisallowFlashFullScreen(true) disallows <embed allowFullScreen="true"><xsl:apply-templates/></embed>
```

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

### Generate PHP Renderers with Custom Class Name

Source: https://github.com/s9e/textformatter/blob/master/docs/Internals/PHP_renderer.md

Demonstrates generating PHP renderers, including setting a custom class name and accessing the last generated class and file path.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->rendering->engine           = 'PHP';
$configurator->rendering->engine->cacheDir = '/tmp';

extract($configurator->finalize());
echo 'Default: ', get_class($renderer), "\n";

$configurator->rendering->engine->className = 'MyRenderer';
extract($configurator->finalize());
echo 'Custom:  ', get_class($renderer), "\n\n";

echo 'Last class: ', $configurator->rendering->engine->lastClassName, "\n";
echo 'Last file:  ', $configurator->rendering->engine->lastFilepath;
```

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

### Rendered HTML for Unsafe Elements Example

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/HTMLElements/Synopsis.md

The resulting HTML after parsing and rendering text containing explicitly allowed unsafe elements and attributes.

```html
<script>alert(1)</script><b onmouseover="alert(1)">Hover me</b>.
```

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

### Discover Configurable Federated Sites

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Federated_sites.md

Iterates through default MediaEmbed sites to find those implementing `ConfigurableHostInterface`, allowing for host configuration via `getSiteHelper()`.

```php
use s9e\TextFormatter\Plugins\MediaEmbed\Configurator\SiteHelpers\ConfigurableHostInterface;

$configurator = new s9e\TextFormatter\Configurator;
foreach ($configurator->MediaEmbed->defaultSites as $siteId => $siteConfig)
{
	if (!isset($siteConfig['helper']))
	{
		continue;
	}

	$siteHelper = $configurator->MediaEmbed->getSiteHelper($siteId);
	if ($siteHelper instanceof ConfigurableHostInterface)
	{
		echo $siteConfig['name'], " is configurable via getSiteHelper('$siteId')->setHosts()\n";
	}
}
```

```html
Bluesky is configurable via getSiteHelper('bluesky')->setHosts()
Mastodon is configurable via getSiteHelper('mastodon')->setHosts()
PeerTube is configurable via getSiteHelper('peertube')->setHosts()
XenForo is configurable via getSiteHelper('xenforo')->setHosts()
```

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

### Disallowed XPath Functions

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Examples of XPath functions that are disallowed in templates due to security risks, such as accessing external documents or executing PHP functions.

```XSLT
<xsl:value-of select="document(@foo)"/>
```

```XSLT
<xsl:value-of select="php:function()"/>
```

```XSLT
<xsl:value-of select="php : function()"/>
```

```XSLT
<b title="...{document()}"/>
```

```XSLT
<b title="...{ document () }"/>
```

```XSLT
<b title="...{ doc&#117;ment () }"/>
```

```XSLT
<b title="{concat(\'}\",document())}"/>
```

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

### Basic Autovideo Plugin Usage

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Autovideo/Synopsis.md

Demonstrates how to load and use the Autovideo plugin to convert a standard MP4 URL into an HTML video tag.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->plugins->load('Autovideo');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'http://example.org/video.mp4';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
<video controls="" src="http://example.org/video.mp4"></video>
```

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

### List BBCode to UL/OL Tags

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/BBCodes/Add_from_the_repository.md

Converts the [LIST] BBCode to HTML <ul> or <ol> tags. Supports different list types and starting numbers.

```bbcode
[LIST type={HASHMAP=1:decimal,a:lower-alpha,A:upper-alpha,i:lower-roman,I:upper-roman;optional;postFilter=#simpletext} start={UINT;optional} #createChild=LI]{TEXT}[/LIST]
```

```xsl
<xsl:choose>
	<xsl:when test="not(@type)">
		<ul><xsl:apply-templates /></ul>
	</xsl:when>
	<xsl:when test="starts-with(@type,'decimal') or starts-with(@type,'lower') or starts-with(@type,'upper')">
		<ol style="list-style-type:{@type}"><xsl:copy-of select="@start"/><xsl:apply-templates /></ol>
	</xsl:when>
	<xsl:otherwise>
		<ul style="list-style-type:{@type}"><xsl:apply-templates /></ul>
	</xsl:otherwise>
</xsl:choose>
```

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

### Allow Script Access with Object Param

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Demonstrates allowed 'allowScriptAccess' configurations for the <object> tag with a parameter when the check is 'sameDomain'.

```html
<object><param name="allowScriptAccess" value="sameDomain"/></object>
```

```html
<object><param name="allowScriptAccess" value="never"/></object>
```

```html
<object/>
```

```html
<object><param name="allowScriptAccess" value="sameDomain"/></object>
```

```html
<object><param name="allowScriptAccess" value="never"/></object>
```

```html
<object/>
```

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

### Multiple Attribute Preprocessors for Flexible Input

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/BBCodes/Custom_BBCode_syntax.md

Demonstrates using multiple {PARSE} tokens to allow a name to be specified as 'First Last' or 'Last, First'.

```BBCode
[name={PARSE=/(?<first>\w+) (?<last>\w+)/} name={PARSE=/(?<last>\w+), (?<first>\w+)/}]
```

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

### Matching 'www.' Hostnames

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Autolink/Synopsis.md

Enables the Autolink plugin to match hostnames starting with 'www.' even if they lack a scheme, automatically prepending 'http://'.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->Autolink->matchWww = true;

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'Link: www.example.org.';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
Link: <a href="http://www.example.org">www.example.org</a>.
```

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

### TextFormatter Processing Phases

Source: https://github.com/s9e/textformatter/blob/master/docs/Getting_started/How_it_works.md

Illustrates the four main stages of text processing: Parsing, Rendering, and Unparsing, starting from original text to HTML and back.

```text
                Parsing 
              ↗         ↘
Original text             XML → Rendering → HTML
              ↖         ↙
               Unparsing
```

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

### Use Live Preview in JavaScript

Source: https://github.com/s9e/textformatter/wiki/Live-Preview

Renders the given text content within the specified HTML element using the TextFormatter library. Ensure the s9e.TextFormatter object is available in the global scope.

```javascript
s9e.TextFormatter.preview(text, el);
```

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

### Basic Autolink Usage

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/Autolink/Synopsis.md

Demonstrates the default behavior of the Autolink plugin, converting 'http://' URLs to clickable links.

```php
$configurator = new s9e\TextFormatter\Configurator;
$configurator->plugins->load('Autolink');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'More info at http://example.org.';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

```html
More info at <a href="http://example.org">http://example.org</a>.
```

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

### Configure Bluesky Media Embed with Custom Hosts

Source: https://github.com/s9e/textformatter/blob/master/docs/Plugins/MediaEmbed/Federated_sites.md

Use the BlueskyHelper to set multiple supported instances for embedding Bluesky content. This allows embedding from both the default 'bsky.app' and custom domains.

```php
$configurator = new s9e\TextFormatter\Configurator;

// Use the Bluesky helper to set 'bsky.app' and 'bluesky.local' as supported instances
$mastodonHelper = $configurator->MediaEmbed->getSiteHelper('bluesky');
$mastodonHelper->setHosts(['bsky.app', 'bluesky.local']);

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = 'https://bsky.app/profile/bsky.app/post/3kkrqzuydho2v';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
```

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

### Allow Networking with Object Param

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

Demonstrates allowed networking configurations for the <object> tag with a 'allowNetworking' parameter.

```html
<object><param name="allowNetworking" value="internal"/></object>
```

```html
<object><param name="allowNetworking" value="none"/></object>
```

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

### Disallowed XSL Attribute with Function Call

Source: https://github.com/s9e/textformatter/blob/master/docs/testdox.txt

An example of a disallowed XSL attribute where a function call is used within curly braces, potentially leading to unsafe evaluation.

```XML
<hr title="{foo()}"/>
```