### Install HTML Purifier with Composer

Source: https://github.com/ezyang/htmlpurifier/blob/master/README.md

This snippet shows how to install the HTML Purifier library using Composer, a dependency manager for PHP. It assumes you have Composer installed and configured.

```Shell
composer require ezyang/htmlpurifier
```

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

### PHP Configuration Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/proposal-plists.txt

Demonstrates adding an AutoFormat plugin to the configuration. This involves using a specific method to enable filters or formatters, potentially with magic backward compatibility.

```PHP
add('AutoFormat', 'AutoParagraph');
```

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

### Setup HTML Purifier Configuration

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-customize.html

Initializes HTML Purifier with custom definition ID and revision. It retrieves a raw HTML definition object, which might be null if cached.

```PHP
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML.DefinitionRev', 1);
if ($def = $config->maybeGetRawHTMLDefinition()) {
    // our code will go here
}
```

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

### Define Configuration Directive

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-includes.txt

Example of defining a configuration directive with its type, default value, aliases, and description. This format is inspired by PHPT and aims to be compact and human-readable.

```PHP
Core.HiddenElements
TYPE:    lookup
DEFAULT: array('script', 'style') // auto-converted during processing
--ALIASES--
Core.InvisibleElements, Core.StupidElements
--DESCRIPTION--
<p>
  Blah blah
</p>
```

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

### HTML Purifier: Regex Content Model Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-customize.html

Illustrates a complex content model using DTD-style regular expressions, specifying the order and quantity of child elements.

```php
$config->set('HTML', 'AllowedChildren', 'a, b?, (c | d), e+, f*');
```

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

### PHP Configuration Structure Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/proposal-plists.txt

Illustrates two ways to structure configuration data in PHP. The first uses nested arrays for namespaces, while the second uses dot-separated strings for a flatter structure. The latter is discussed for its memory implications and ease of retrieval.

```PHP
array(
    'Namespace' => array(
        'Directive' => 'val1',
        'Directive2' => 'val2',
    )
)
```

```PHP
array(
    'Namespace.Directive' => 'val1',
    'Namespace.Directive2' => 'val2',
)
```

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

### HTML Purifier AutoFormat.RemoveEmpty.RemoveNbsp Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-config-naming.txt

Demonstrates how boolean directives in HTML Purifier's AutoFormat namespace can be nested. Specifically, it shows how RemoveEmpty.RemoveNbsp can trigger RemoveEmpty.RemoveNbsp.Exceptions, highlighting the dependency between these configuration options.

```text
RemoveEmpty.RemoveNbsp triggers RemoveEmpty.RemoveNbsp.Exceptions
```

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

### HTMLPurifier HTML.BlockWrapper Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/HTML.BlockWrapper.txt

Demonstrates how the HTML.BlockWrapper setting affects the output of HTMLPurifier. Inline elements within a block context, such as a blockquote, are wrapped with the specified block-level element.

```html
<blockquote>Foo</blockquote>
```

```html
<blockquote><p>Foo</p></blockquote>
```

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

### Example Custom URI Filter - TransformImageScheme

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-uri-filter.html

Provides a concrete example of a custom URI filter that transforms URIs with an 'image' scheme to a standard HTTP path. It demonstrates modifying the URI object within the filter method.

```PHP
class HTMLPurifier_URIFilter_TransformImageScheme extends HTMLPurifier_URIFilter
{
    public $name = 'TransformImageScheme';
    public function filter(&$uri, $config, $context) {
        if ($uri->scheme !== 'image') return true;
        $img_name = $uri->path;
        // Overwrite the previous URI object
        $uri = new HTMLPurifier_URI('http', null, null, null, '/img/' . $img_name . '.png', null, null);
        return true;
    }
}
```

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

### Configure SafeIframeRegexp for YouTube and Vimeo

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/URI.SafeIframeRegexp.txt

This example illustrates setting URI.SafeIframeRegexp to accept iframes from both YouTube and Vimeo embed URLs. It uses a combined regular expression for broader compatibility.

```html
<pre><code>%URI.SafeIframeRegexp = '%^http://(www.youtube.com/embed/|player.vimeo.com/video/)%';</code></pre>
```

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

### Configure SafeIframeRegexp for Vimeo

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/URI.SafeIframeRegexp.txt

This example shows how to configure URI.SafeIframeRegexp to permit iframes from Vimeo's video player URL. This setting enhances security by controlling which external video sources are allowed.

```html
<pre><code>%URI.SafeIframeRegexp = '%^http://player.vimeo.com/video/%';</code></pre>
```

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

### Inbound Filtering with HTML Purifier (PHP)

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-slow.html

This example demonstrates how to perform inbound filtering of user-submitted HTML using the HTML Purifier library. It shows the process of receiving HTML from a form submission, purifying it, and then inserting the clean HTML into a database. The code assumes the existence of helper functions for displaying errors, success messages, forms, and database insertion.

```PHP
<?php
    /**
     * FORM SUBMISSION PAGE
     * display_error($message) : displays nice error page with message
     * display_success() : displays a nice success page
     * display_form() : displays the HTML submission form
     * database_insert($html) : inserts data into database as new row
     */
    if (!empty($_POST)) {
        require_once '/path/to/library/HTMLPurifier.auto.php';
        require_once 'HTMLPurifier.func.php';
        $dirty_html = isset($_POST['html']) ? $_POST['html'] : false;
        if (!$dirty_html) {
            display_error('You must write some HTML!');
        }
        $html = HTMLPurifier($dirty_html);
        database_insert($html);
        display_success();
        // notice that $dirty_html is *not* saved
    } else {
        display_form();
    }
?>
```

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

### HTML Purifier: Custom Content Model Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-customize.html

Demonstrates a custom content model for an element requiring at least one 'li' child, specified as 'Required: li'.

```php
$config->set('HTML', 'AllowedChildren', 'Required: li');
```

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

### URI Munging with Additional Substitutions

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/URI.Munge.txt

This example shows how to use HTML Purifier's URI.Munge directive with advanced substitutions like %r (resource indicator), %n (tag name), %m (attribute name), and %p (CSS property name) for more granular control over URI redirection.

```php
$config->set('URI', 'Munge', 'http://example.com/redirect?resource=%r&tag=%n&attr=%m&prop=%p');
```

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

### Initialize HTML Purifier configuration

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-customize.html

This PHP code snippet shows the initial setup for configuring HTML Purifier. It creates a default configuration object and sets specific definition identifiers and revision numbers, which are crucial for custom HTML definitions.

```PHP
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML.DefinitionRev', 1);
$def = $config->getHTMLDefinition(true);
```

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

### Extract Style Blocks with HTML Purifier and CSSTidy (PHP)

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/Filter.ExtractStyleBlocks.txt

This snippet demonstrates how to configure HTML Purifier to extract style blocks from HTML content. It utilizes CSSTidy for cleaning the extracted styles and shows how to save them to files or include them in the document. The example includes setting up HTML Purifier, processing dirty HTML, and handling the extracted styles.

```php
<?php
    header('Content-type: text/html; charset=utf-8');
    echo '<?xml version="1.0" encoding="UTF-8"?>';
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
  <title>Filter.ExtractStyleBlocks</title>
<?php
    require_once '/path/to/library/HTMLPurifier.auto.php';
    require_once '/path/to/csstidy.class.php';

    $dirty = '<style>body {color:#F00;}</style> Some text';

    $config = HTMLPurifier_Config::createDefault();
    $config->set('Filter', 'ExtractStyleBlocks', true);
    $purifier = new HTMLPurifier($config);

    $html = $purifier->purify($dirty);

    // This implementation writes the stylesheets to the styles/ directory.
    // You can also echo the styles inside the document, but it's a bit
    // more difficult to make sure they get interpreted properly by
    // browsers; try the usual CSS armoring techniques.
    $styles = $purifier->context->get('StyleBlocks');
    $dir = 'styles/';
    if (!is_dir($dir)) mkdir($dir);
    $hash = sha1($_GET['html']);
    foreach ($styles as $i => $style) {
        file_put_contents($name = $dir . $hash . "_$i");
        echo '<link rel="stylesheet" type="text/css" href="'.$name.'" />';
    }
?>
</head>
<body>
  <div>
    <?php echo $html; ?>
  </div>
</body>
</html>
```

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

### HTML Purifier Hierarchy Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/proposal-errors.txt

This illustrates the current and potential hierarchical relationships between different HTML elements and their properties as processed by HTML Purifier. It shows the progression from tokens to attributes to CSS properties, and suggests future extensions.

```N/A
token -> attr -> css property

* -> syntax
  -> token -> attr -> css property
                       -> url
           -> css stylesheet <style>
```

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

### Configure SafeIframeRegexp for YouTube

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/URI.SafeIframeRegexp.txt

This example demonstrates how to set the URI.SafeIframeRegexp to allow iframes from YouTube's embed URL. This configuration is part of HTML Purifier's security features for handling embedded content.

```html
<pre><code>%URI.SafeIframeRegexp = '%^http://www.youtube.com/embed/%';</code></pre>
```

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

### Caching Filtered HTML Output with HTML Purifier (PHP)

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-slow.html

This example illustrates a strategy for improving performance by caching the filtered HTML output. When a page is requested, the system first attempts to retrieve the HTML from a cache. If it's not found in the cache, the raw HTML is fetched from the database, purified using HTML Purifier, stored in the cache, and then displayed. This approach ensures that filtering is only performed when necessary.

```PHP
<?php
    /**
     * VIEW PAGE
     * display_error($message) : displays nice error page with message
     * cache_get($id) : retrieves HTML from fast cache (db or file)
     * cache_insert($id, $html) : inserts good HTML into cache system
     * database_get($id) : retrieves raw HTML from database
     */
    $id = isset($_GET['id']) ? (int) $_GET['id'] : false;
    if (!$id) {
        display_error('Must specify ID.');
        exit;
    }
    $html = cache_get($id); // filesystem or database
    if ($html === false) {
        // cache didn't have the HTML, generate it
        $raw_html = database_get($id);
        require_once '/path/to/library/HTMLPurifier.auto.php';
        require_once 'HTMLPurifier.func.php';
        $html = HTMLPurifier($raw_html);
        cache_insert($id, $html);
    }
    echo $html;
?>
```

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

### Example HTTP Content-Type Header

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-utf8.html

This example demonstrates a typical Content-Type HTTP header sent by a web server, specifying the MIME type and character encoding of the response. This header works in conjunction with or as an alternative to META tags for encoding declaration.

```HTTP
Content-Type: text/html; charset=ISO-8859-1
```

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

### PHP Configuration Loading and Saving

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/proposal-plists.txt

Demonstrates a common pattern for managing HTML Purifier configuration by loading from or saving to a file. This approach allows for persistent configuration and can be integrated with caching mechanisms.

```PHP
$config = HTMLPurifier_Config::createDefault();
if (!file_exists('config.php')) {
    // set up $config
    $config->save('config.php');
} else {
    $config->load('config.php');
}
```

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

### Disallow Attribute Globally (PHP)

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/HTML.ForbiddenAttributes.txt

This example shows how to globally disallow an attribute across all HTML tags using the HTML.ForbiddenAttributes directive. The syntax 'attr' or '*@attr' can be used.

```php
$config->set('HTML', 'ForbiddenAttributes', ['href']);
```

```php
$config->set('HTML', 'ForbiddenAttributes', ['*@href']);
```

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

### Vim Configuration

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/ref-whatwg.txt

Vim editor settings for indentation and spacing, commonly used in project configuration files.

```vim
vim: et sw=4 sts=4
```

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

### Specifying UTF-8 in XML

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-utf8.html

Provides an example of an XML declaration that explicitly sets the encoding to UTF-8. This is crucial for ensuring XML documents are interpreted correctly.

```XML
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <element>This is UTF-8 content.</element>
</root>
```

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

### Disallow Attribute in Specific Tag (PHP)

Source: https://github.com/ezyang/htmlpurifier/blob/master/library/HTMLPurifier/ConfigSchema/schema/HTML.ForbiddenAttributes.txt

This example demonstrates how to disallow a specific attribute (e.g., 'href') within a particular HTML tag (e.g., 'a') using the HTML.ForbiddenAttributes directive.

```php
$config->set('HTML', 'ForbiddenAttributes', ['a@href']);
```

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

### Specify Directive Version and Allowed Values

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-includes.txt

Demonstrates how to specify the version of a directive and its allowed values. This allows for better control and validation of configuration settings.

```PHP
VERSION:  3.0.0
ALLOWED:  'none', 'light', 'medium', 'heavy' // this is wrapped in array()
EXTERNAL: CSSTidy // this would be documented somewhere else with a URL
```

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

### PHP Autoloading for HTML Purifier

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-includes.txt

Demonstrates how PHP's autoloader can be used to manage class dependencies for HTML Purifier, simplifying the inclusion of optional components and improving performance. This approach avoids the need for explicit `require_once` calls within functions.

```PHP
spl_autoload_register(function ($class) {
    // Logic to include the class file based on its name
    // For example: require_once 'lib/' . $class . '.php';
});

// Usage example:
// $purifier = new HTMLPurifier();
// Or accepting an object from a caller:
// $purifier = $caller->getPurifierObject();
```

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

### Percent Encoding Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-utf8.html

Illustrates the percent encoding format used in `application/x-www-form-urlencoded` submissions, where characters are represented as `%` followed by their hexadecimal byte values, like `%C3%86`.

```URL Encoding
%C3%86
```

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

### Character Entity Reference Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-utf8.html

Demonstrates the use of character entity references for special characters, such as `&theta;` for the Greek letter theta, and numeric entity references for Chinese characters.

```HTML
For instance, θ can be written `&theta;`, regardless of the character encoding's support of Greek letters.

&#28608;&#20809;, &#36889;&#20841;&#20491;&#23383;&#26159;&#29978;&#40636;&#24847;&#24605;
```

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

### Set Configuration Directive (HTML Purifier)

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-config-bcbreaks.txt

Demonstrates the new syntax for setting configuration directives in HTML Purifier. The old syntax using separate namespace and directive arguments is replaced by a single key argument combining both.

```PHP
$config->set('HTML', 'Allowed', 'p');

// Becomes:
$config->set('HTML.Allowed', 'p');
```

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

### HTML Purifier URI.Directives List

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-config-naming.txt

Details the directives within the URI.* namespace of HTML Purifier, focusing on scheme tuning, global environment settings, caching, contextual/authority tuning, and transformation behavior. This includes managing allowed schemes, default schemes, host blacklists, and resource munge keys.

```text
AllowedSchemes
OverrideAllowedSchemes
    Scheme tuning
Base
DefaultScheme
Host
    Global environment
DefinitionID
DefinitionRev
    Caching
DisableExternalResources
DisableExternal
DisableResources
Disable
    Contextual/authority tuning
HostBlacklist
    Authority tuning
MakeAbsolute
MungeResources
MungeSecretKey
Munge
    Transformation behavior (munge can be grouped)
```

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

### Indicate File Dependencies for Directives

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-includes.txt

Shows how to specify that a configuration directive requires a particular file or class to be included. This ensures that necessary components are available when a directive is used.

```PHP
REQUIRES: HTMLPurifier_Filter_ExtractStyleBlocks
```

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

### Load Custom Schema Directory in PHP

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-config-schema.html

This PHP code snippet demonstrates how to load custom schema definitions from a directory using the `$builder->buildDir()` method. This is typically placed in a `config-schema.php` file within the HTML Purifier base directory.

```php
$builder->buildDir($interchange, '/var/htmlpurifier/myschema');
```

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

### HTML Purifier UTF-8 Handling Example

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-utf8.html

Illustrates the process of character entity handling in HTML Purifier when dealing with different character sets. It shows how unsupported characters are handled, leading to potential data loss or replacement.

```text
Input: `&theta;` (output in Latin-1)

1. Encoder: ISO 8859-1 to UTF-8 -> `&theta;`
2. EntityParser: `&theta;` to `θ`
3. HTML Purifier processes: `θ`
4. Encoder: UTF-8 to ISO 8859-1 -> `?` (unsupported character ignored/replaced)
```

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

### HTML Purifier HTML.Directives List

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/dev-config-naming.txt

Provides a comprehensive list of directives under the HTML.* namespace in HTML Purifier. These directives are used for tuning element sets, managing doctypes, caching definitions, and handling global environment settings, proprietary tags, and Tidy integration.

```text
AllowedAttributes
AllowedElements
AllowedModules
Allowed
ForbiddenAttributes
ForbiddenElements
    Element set tuning
BlockWrapper
    Child def advanced twiddle
CoreModules
CustomDoctype
    Advanced HTMLModuleManager twiddles
DefinitionID
DefinitionRev
    Caching
Doctype
Parent
Strict
XHTML
    Global environment
MaxImgLength
    Attribute twiddle? (applies to two attributes)
Proprietary
SafeEmbed
SafeObject
Trusted
    Extra functionality/tagsets
TidyAdd
TidyLevel
TidyRemove
    Tidy
```

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

### Add Target Attribute to Anchor Tag (Direct)

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-customize.html

This example demonstrates a direct method to add the 'target' attribute to an 'a' tag within HTML Purifier configuration. It retrieves the HTML definition and then adds the attribute, suitable for scenarios where caching is not a primary concern.

```PHP
$config = HTMLPurifier_Config::createDefault();
$def = $config->getHTMLDefinition(true);
$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');
$purifier = new HTMLPurifier($config);
```

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

### Enable p@align Fix in HTML Purifier (PHP)

Source: https://github.com/ezyang/htmlpurifier/blob/master/docs/enduser-tidy.html

This example shows how to configure HTML Purifier to apply only the 'p@align' fix while disabling all other transformations. It sets the doctype and tidy level to 'none', then explicitly adds the 'p@align' rule.

```PHP
$config->set('HTML.Doctype', 'XHTML 1.0 Transitional');
$config->set('HTML.TidyLevel', 'none');
$config->set('HTML.TidyAdd', 'p@align');
```