README

App HTML Sanitizer to sanitize untrusted HTML code.

Table of Contents

• Getting Started
  • Requirements
• Documentation
  • App
  • Sanitizer Boot
    • Sanitizer Config
  • Basic Usage
    • Sanitizing HTML
    • Sanitizing HTML in Views
    • Sanitizing HTML using Function
  • Available Sanitizers
    • Purifier Sanitizer
    • Symfony Sanitizer
  • Adding Sanitizers
• Credits

Getting Started

Add the latest version of the app HTML Sanitizer project running this command.

composer require tobento/app-html-sanitizer

Requirements

• PHP 8.4 or greater

Documentation

App

Check out the App Skeleton if you are using the skeleton.

You may also check out the App to learn more about the app in general.

Sanitizer Boot

The sanitizer boot does the following:

• installs and loads html sanitizer config file
• implements html sanitizer interfaces

use Tobento\App\AppFactory;
use Tobento\App\HtmlSanitizer\HtmlSanitizerInterface;
use Tobento\App\HtmlSanitizer\HtmlSanitizersInterface;

// Create the app
$app = new AppFactory()->createApp();

// Add directories:
$app->dirs()
    ->dir(realpath(__DIR__.'/../'), 'root')
    ->dir(realpath(__DIR__.'/../app/'), 'app')
    ->dir($app->dir('app').'config', 'config', group: 'config')
    ->dir($app->dir('root').'public', 'public')
    ->dir($app->dir('root').'vendor', 'vendor');

// Adding boots:
$app->boot(\Tobento\App\HtmlSanitizer\Boot\HtmlSanitizer::class);
$app->booting();

// Implemented interfaces:
$htmlSanitizer = $app->get(HtmlSanitizerInterface::class);
$htmlSanitizers = $app->get(HtmlSanitizersInterface::class);

// Run the app
$app->run();

Sanitizer Config

The configuration for the sanitizer is located in the app/config/html_sanitizer.php file at the default App Skeleton config location where you can configure sanitizers for your application.

Basic Usage

Sanitizing HTML

use Tobento\App\HtmlSanitizer\HtmlSanitizerInterface;

$htmlSanitizer = $app->get(HtmlSanitizerInterface::class);

$safeHtml = $htmlSanitizer->sanitize(html: $html);

$safeHtml = $htmlSanitizer->sanitizeFor(element: 'h1' html: $html);

Using Specific Sanitizer

use Tobento\App\HtmlSanitizer\HtmlSanitizersInterface;

$htmlSanitizers = $app->get(HtmlSanitizersInterface::class);

$htmlSanitizer = $htmlSanitizers->get(name: 'custom');

$safeHtml = $htmlSanitizer->sanitize(html: $html);

$safeHtml = $htmlSanitizer->sanitizeFor(element: 'h1' html: $html);

Sanitizing HTML in Views

If you have installed the App View, you may use the sanitizeHtml and sanitizeHtmlFor view macro to sanitize untrusted HTML:

<!-- Using the default -->
<?= $view->sanitizeHtml($html) ?>

<!-- Or using a specific sanitizer -->
<?= $view->sanitizeHtml(html: $html, sanitizer: 'name') ?>

<!-- Using the default -->
<?= $view->sanitizeHtmlFor('h1', $html, 'named') ?>

<!-- Or using a specific sanitizer -->
<?= $view->sanitizeHtmlFor(element: 'h1', html: $html, sanitizer: 'name') ?>

Sanitizing HTML using Function

use function Tobento\App\HtmlSanitizer\{sanitizeHtml, sanitizeHtmlFor};

$safeHtml = sanitizeHtml($html);
// Or using a specific sanitizer
$safeHtml = sanitizeHtml(html: $html, sanitizer: 'name');

$safeHtml = sanitizeHtmlFor('h1', $html, 'named');
// Or using a specific sanitizer
$safeHtml = sanitizeHtmlFor(element: 'h1', html: $html, sanitizer: 'name');

Available Sanitizers

Purifier Sanitizer

First, you will need to install it:

composer require ezyang/htmlpurifier

This HTML sanitizer uses the Ezyang HTML Purifier.

In the Sanitizer Config file, you can configure this sanitizer using the Purifier\HtmlSanitizerFactory::class:

use Tobento\App\HtmlSanitizer\Purifier;
use function Tobento\App\{directory};

return [
    'sanitizers' => [
        'default' => new Purifier\HtmlSanitizerFactory([
            'Cache.SerializerPath' => directory('app').'storage/html-sanitizer/purifier',
            'Cache.SerializerPermissions' => 0755,
            'Attr.AllowedFrameTargets' => ['_blank'],
        ]),
    ],
];

Visit the Ezyang HTML Purifier for more information.

Symfony Sanitizer

This HTML sanitizer uses the Symfony HTML Sanitizer which is the default sanitizer, no need to install.

In the Sanitizer Config file, you can configure this sanitizer using the Symfony\HtmlSanitizerFactory::class:

use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;
use Tobento\App\HtmlSanitizer\Symfony;

return [
    'sanitizers' => [
        'default' => new Symfony\HtmlSanitizerFactory(
            htmlSanitizerConfig: new HtmlSanitizerConfig()
                ->allowSafeElements()
                ->allowAttribute('class', '*')
                ->forceAttribute('a', 'rel', 'noopener noreferrer')
        ),
    ],
];

Visit the Symfony HTML Sanitizer for more information.

Adding Sanitizers

In addition to adding sanitizers in the Sanitizer Config file, you may adding them using a boot:

use Tobento\App\Boot;
use Tobento\App\HtmlSanitizer\HtmlSanitizerFactoryInterface;
use Tobento\App\HtmlSanitizer\HtmlSanitizerInterface;
use Tobento\App\HtmlSanitizer\HtmlSanitizersInterface;

class HtmlSanitizersBoot extends Boot
{
    public const BOOT = [
        // you may ensure the sanitizer boot.
        \Tobento\App\HtmlSanitizer\Boot\HtmlSanitizer::class,
    ];
    
    public function boot()
    {
        // you may use the app on method to add only if requested:
        $app->on(
            HtmlSanitizersInterface::class,
            static function(HtmlSanitizersInterface $htmlSanitizers) {
                $htmlSanitizers->add(
                    name: 'custom',
                    sanitizer: $sanitizer, // HtmlSanitizerFactoryInterface|HtmlSanitizerInterface
                );
            }
        );
    }
}

Credits

• Tobias Strub
• All Contributors