Purify

https://github.com/stevebauman/purify
Admin
Purify is a Laravel wrapper for HTMLPurifier, providing a convenient way to clean user input and...
Tokens:39,266
Snippets:312
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### getPurifier() basic usage

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify.md

Example of retrieving the purifier instance with a custom configuration and using it directly.

```php
use Stevebauman\Purify\Facades\Purify;

$purifier = Purify::config(['HTML.Allowed' => 'p'])->getPurifier();

echo get_class($purifier); // HTMLPurifier
echo $purifier->purify('<p>a</p><div>b</div>'); // <p>a</p>b
```

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

### Install Purify with Composer

Source: https://github.com/stevebauman/purify/blob/master/README.md

Installs the Purify package via Composer in the root of your project.

```bash
composer require stevebauman/purify
```

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

### Usage example with facade and app()

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-service-provider.md

Shows how to resolve the 'purify' singleton via the facade or the app() helper, and asserts it is a PurifyManager instance.

```php
use Stevebauman\Purify\Facades\Purify;

// The facade resolves the 'purify' singleton => PurifyManager.
$manager = app('purify');
assert($manager instanceof \Stevebauman\Purify\PurifyManager);
```

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

### Create and register a custom CSS definition

Source: https://github.com/stevebauman/purify/blob/master/README.md

Create a custom CSS definition implementing CssDefinition and reference it in the 'css-definitions' key of config/purify.php. The example overrides text-align to include start and end values.

```php
namespace App;

use HTMLPurifier_CSSDefinition;
use Stevebauman\Purify\Definitions\CssDefinition;

class CustomCssDefinition implements CssDefinition
{
    /**
     * Apply rules to the CSS Purifier definition.
     *
     * @param HTMLPurifier_CSSDefinition $definition
     *
     * @return void
     */
    public static function apply(HTMLPurifier_CSSDefinition $definition)
    {
        // Customize the CSS purifier definition.
        $definition->info['text-align'] = new \HTMLPurifier_AttrDef_Enum(
            ['right', 'left', 'center', 'start', 'end'],
            false,
        );
    }
}
```

```php
// config/purify.php

'css-definitions' => \App\CustomCssDefinition::class,
```

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

### Purify usage example

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify.md

Demonstrates creating a Purify instance with a specific configuration and using the clean method to sanitize HTML.

```php
use HTMLPurifier_Config;
use Stevebauman\Purify\Purify;

$config = HTMLPurifier_Config::create(['HTML.Allowed' => 'p,b']);
$purify = new Purify($config);

echo $purify->clean('<script>alert("x")</script><p>ok</p>'); // <p>ok</p>
```

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

### get($config)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Retrieves a definition object from the cache. Returns false when the key is missing, otherwise the decoded definition.

```APIDOC
## get($config)

### Description
Retrieves a definition object from the cache. Returns false when the key is missing, otherwise the decoded definition.

### Method
get

### Signature
public function get($config)

### Parameters
- **$config** (HTMLPurifier_Config) - Required - The configuration object.

### Return Value
- **bool|HTMLPurifier_Definition** - Returns false if key missing, otherwise the decoded definition.
```

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

### clean() with array input and custom configuration

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify.md

Example of sanitizing an array of strings using a specific configuration set.

```php
use Stevebauman\Purify\Facades\Purify;

$array = [
    '<script>alert("x");</script><a href="https://example.com">link</a>',
    '<b>bold</b>',
];

$cleaned = Purify::config('default')->clean($array);

// array: ['<a href="https://example.com">link</a>', '<b>bold</b>']
```

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

### get($config) method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Retrieves a definition object from the cache. Returns false if the file does not exist, otherwise returns the unserialized definition object.

```php
/**
 * Retrieves a definition object from the cache.
 *
 * @param \HTMLPurifier_Config $config
 *
 * @return bool|\HTMLPurifier_Config
 */
public function get($config)
```

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

### clean() basic usage

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify.md

Example of sanitizing a string containing harmful scripts and styled HTML using the default configuration.

```php
use Stevebauman\Purify\Facades\Purify;

$input = '<script>alert("Harmful Script");</script> <p style="border:1px solid black" class="text-gray-700">Test</p>';

$cleaned = Purify::clean($input);

// With the default config set, returns: '<p>Test</p>'
echo $cleaned;
```

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

### Extending Built-in Definitions

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/types.md

Example of extending the existing Html5Definition by calling its apply method before adding custom elements.

```php
use Stevebauman\Purify\Definitions\Html5Definition;

public static function apply(HTMLPurifier_HTMLDefinition $definition)
{
    Html5Definition::apply($definition); // start from the shipped HTML5 set

    $definition->addElement('main', 'Block', 'Flow', 'Common');
}
```

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

### Purify::driver($driver = null)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/facade.md

Gets a driver instance. This is a static call that forwards to the `PurifyManager::driver()` method.

```APIDOC
## Purify::driver($driver = null)

### Description
Gets a driver instance. This is a static call that forwards to the `PurifyManager::driver()` method.

### Method
Static method on the facade.

### Parameters
- **$driver** (string|null) - Optional - The driver name. If null, the default driver is used.

### Returns
- **\Stevebauman\Purify\Purify** - The driver instance.
```

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

### Custom Definition Implementation

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/types.md

An example of implementing the Definition interface to add a custom attribute to span elements.

```php
namespace App;

use HTMLPurifier_HTMLDefinition;
use Stevebauman\Purify\Definitions\Definition;

class CustomDefinition implements Definition
{
    public static function apply(HTMLPurifier_HTMLDefinition $definition)
    {
        $definition->addAttribute('span', 'data-id', 'Number');
    }
}
```

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

### CustomCssDefinition Implementation

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/types.md

An example implementation of the CssDefinition interface to add support for text-align enum values.

```php
namespace App;

use HTMLPurifier_CSSDefinition;
use Stevebauman\Purify\Definitions\CssDefinition;

class CustomCssDefinition implements CssDefinition
{
    public static function apply(HTMLPurifier_CSSDefinition $definition)
    {
        $definition->info['text-align'] = new \HTMLPurifier_AttrDef_Enum(
            ['right', 'left', 'center', 'start', 'end'],
            false,
        );
    }
}
```

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

### Configure filesystem serializer in config/purify.php

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/clear-command.md

Configuration snippet for the filesystem serializer, specifying disk, path, and cache class. This is used with the filesystem cache example.

```php
// config/purify.php
'serializer' => [
    'disk' => env('FILESYSTEM_DISK', 'local'),
    'path' => 'purify',
    'cache' => \Stevebauman\Purify\Cache\FilesystemDefinitionCache::class,
],
```

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

### Verify apply() with direct HTMLPurifier usage

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/html5-definition.md

Shows that elements not in HTML.Allowed are stripped regardless of the definition. The example applies Html5Definition to a config allowing only 'video[src|controls]', then purifies a video with an autoplay attribute, which is dropped because autoplay is not defined.

```php
use HTMLPurifier;
use HTMLPurifier_Config;
use Stevebauman\Purify\Definitions\Html5Definition;

$config = HTMLPurifier_Config::create(['HTML.Allowed' => 'video[src|controls]']);
$htmlDef = $config->maybeGetRawHTMLDefinition();
Html5Definition::apply($htmlDef);

$purifier = new HTMLPurifier($config);
echo $purifier->purify('<video src="a.mp4" controls autoplay>b</video>');
// '<video src="a.mp4" controls="">b</video>' — autoplay is not defined, so it is dropped
```

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

### getDefaultDriver()

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Get the default driver name.

```APIDOC
## getDefaultDriver()

### Description
Get the default driver name.

### Method
`getDefaultDriver()`

### Signature
```php
public function getDefaultDriver()
```

### Returns
- **string** - The value of the `purify.default` configuration key. Defaults to `'default'` in the shipped `config/purify.php`.

### Throws
- Nothing. Note: if this returns `null`, the inherited `Manager::driver()` throws `InvalidArgumentException` ("Unable to resolve NULL driver for ...") - behavior from `Illuminate\Support\Manager`, not this file.

### Example
```php
use Stevebauman\Purify\Facades\Purify;

echo Purify::getDefaultDriver(); // 'default'
```
```

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

### Diagnose CacheDefinitionCache with get() and flush()

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Direct interaction with CacheDefinitionCache for diagnosis. Creates a cache instance with the 'HTML' definition, sets a DefinitionID and DefinitionRev, then checks for a cached definition (returns false when nothing is cached) and flushes the entire configured cache store.

```php
use Stevebauman\Purify\Cache\CacheDefinitionCache;
use HTMLPurifier_Config;

$cache = new CacheDefinitionCache('HTML');

$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.DefinitionID', 'HTML-purify');
$config->set('HTML.DefinitionRev', 1);

var_dump($cache->get($config));   // false when nothing cached yet
$cache->flush($config);           // wipes the whole configured cache store
```

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

### driver()

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Get a driver instance. Overrides Manager::driver(). Resolves a Purify instance using a config set name, an inline config array, or the default.

```APIDOC
## driver()

### Description
Get a driver instance. Overrides `Manager::driver()`. Resolves a Purify instance using a config set name, an inline config array, or the default.

### Method
`driver()`

### Signature
```php
public function driver($driver = null)
```

### Parameters
- **$driver** (`string|array|null`) - Optional - Config set name, inline config array, or `null` for the default.

### Returns
- **Purify** - The same (memoized) instance for a given name; a fresh instance per inline array.

### Throws
- **InvalidArgumentException** - When the resolved name has no `purify.configs.<name>` entry and no custom creator.

### Behavior
An inline array is **not merged** with the default set; it becomes its own config set keyed by `md5(serialize($driver))`, stored at runtime under `purify.configs.<md5>`. Identical arrays produce the same key, so the same `Purify` instance is reused (and the key may collide with a previously defined name equal to that md5 hash). The driver memoization then happens in the inherited `Manager::driver()`.

### Example - inline configuration
```php
use Stevebauman\Purify\Facades\Purify;

$cleaned = Purify::config(['HTML.Allowed' => 'div,b,a[href]'])->clean($input);
```

### Example - unknown name raises an exception
```php
use Stevebauman\Purify\Facades\Purify;

try {
    Purify::driver('does-not-exist');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // Purify config [does-not-exist] not defined.
}
```
```

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

### Error handling for undefined cast config set

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

Illustrates the exception thrown when a named config set is not defined, with a try-catch example.

```php
class Post extends Model
{
    protected function casts()
    {
        return [
            'content' => PurifyHtmlOnGet::class.':typo-set',
        ];
    }
}

try {
    $post = Post::find(1);
    echo $post->content; // PurifyManager::driver('typo-set') throws
} catch (\InvalidArgumentException $e) {
    // "Purify config [typo-set] not defined."
}
```

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

### PurifyHtmlOnGet get Method Implementation

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

The implementation of the get method, which returns null if the value is null, or the purified value using the configured Purify instance.

```php
public function get($model, $key, $value, $attributes)
{
    if (is_null($value)) {
        return null;
    }

    return Purify::config($this->config)->clean($value);
}
```

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

### getPurifier() advanced usage

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify.md

Example of using the underlying HTMLPurifier library's serial-mode purification API directly.

```php
use Stevebauman\Purify\Facades\Purify;

$config = ['Cache.SerializerPath' => null];
$purifier = Purify::config($config)->getPurifier();

// Use the underlying library's serial-mode purification API directly.
$serial = $purifier->purify('<b>bold</b>', true);
```

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

### Extend Html5Definition in custom definition class

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/html5-definition.md

The README pattern for a custom definition: call Html5Definition::apply($definition) first, then add your own rules. The example adds a 'data-trix-id' attribute to anchor elements.

```php
namespace App;

use HTMLPurifier_HTMLDefinition;
use Stevebauman\Purify\Definitions\Definition;
use Stevebauman\Purify\Definitions\Html5Definition;

class CustomDefinition implements Definition
{
    public static function apply(HTMLPurifier_HTMLDefinition $definition)
    {
        Html5Definition::apply($definition);

        $definition->addAttribute('a', 'data-trix-id', 'Number');
    }
}
```

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

### Clean HTML5 elements with default definition (Purify::config)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/html5-definition.md

Because purify.definitions defaults to Html5Definition::class, HTML5 elements survive cleaning when allowed by the config set. The example cleans an article containing header and h1 elements using the HTML.Allowed config.

```php
use Stevebauman\Purify\Facades\Purify;

$html = '<article><header><h1>Title</h1></header><p>Body</p></article>';

$cleaned = Purify::config(['HTML.Allowed' => 'article,header,h1,p'])->clean($html);
// '<article><header><h1>Title</h1></header><p>Body</p></article>'
```

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

### boot() method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-service-provider.md

Defines the boot method with a docblock. It is called after all providers are registered.

```php
/**
 * Register the publishable configuration.
 *
 * @return void
 */
public function boot()
```

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

### Publishing configuration in boot()

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-service-provider.md

Publishes the package configuration file to the application's config directory under the 'config' group. Only runs in console.

```php
$this->publishes([
    __DIR__.'/../config/purify.php' => config_path('purify.php'),
], 'config');
```

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

### PurifyHtmlOnSet get method

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

The get method implementation for the cast, which returns the stored value unmodified.

```php
/**
 * Cast the given value.
 *
 * @param \Illuminate\Database\Eloquent\Model $model
 * @param string                              $key
 * @param mixed                               $value
 * @param array                               $attributes
 *
 * @return string|array|null
 */
public function get($model, string $key, $value, array $attributes)
```

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

### Config-set usage

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/facade.md

Demonstrates how to use a specific configuration set by calling config() before invoking clean().

```php
use Stevebauman\Purify\Facades\Purify;

$cleaned = Purify::config(['HTML.Allowed' => 'b'])->clean('<b>ok</b><i>no</i>');
// '<b>ok</b>no'
```

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

### PurifyHtmlOnGet get Method Signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

The method signature for the get operation, which defines the parameters for purifying model attributes.

```php
/**
 * Purify the given value.
 *
 * @param \Illuminate\Database\Eloquent\Model $model
 * @param string                              $key
 * @param mixed                               $value
 * @param array                               $attributes
 *
 * @return string|array|null
 */
public function get($model, $key, $value, $attributes)
```

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

### Basic usage

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/facade.md

Demonstrates the standard usage of the Purify facade to clean HTML input using the default configuration.

```php
use Stevebauman\Purify\Facades\Purify;

$cleaned = Purify::clean('<script>alert("x")</script><p>Test</p>');
// '<p>Test</p>'
```

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

### prepareFilesystemStorage method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Protected method that makes the serializer directory on the configured Laravel disk if it does not exist.

```php
protected function prepareFilesystemStorage(string $serializerPath)
```

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

### Purify::config() default configuration usage

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Demonstrates using the config() method without arguments to utilize the default purify.default configuration set.

```php
use Stevebauman\Purify\Facades\Purify;

$purify = Purify::config(); // Uses config: purify.default
echo $purify->clean('<b>x</b>');
```

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

### provides() method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-service-provider.md

Defines the provides method with a docblock. It returns the list of services provided by the provider.

```php
/**
 * Get the services provided by the provider.
 *
 * @return array
 */
public function provides()
```

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

### add($def, $config) method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Adds a definition object to the cache. Returns void on type mismatch, false if the file exists, or the result of the disk put operation.

```php
/**
 * Adds a definition object to the cache.
 *
 * @param \HTMLPurifier_Definition $def
 * @param \HTMLPurifier_Config     $config
 *
 * @return bool|void
 */
public function add($def, $config)
```

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

### FilesystemDefinitionCache constructor

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Constructor for the FilesystemDefinitionCache class. It takes a definition type ('HTML' or 'CSS') and passes it to the parent constructor. The disk is stored as an Illuminate\Contracts\Filesystem\Filesystem instance.

```php
/**
 * Constructor.
 *
 * @param string $type
 */
public function __construct($type)
```

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

### createInstance method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Protected method that creates a Purify instance. Calls prepareFilesystemStorage() when a serializer path exists, then constructs a new Purify with the merged config.

```php
protected function createInstance(string $name, array $config)
```

```php
return new Purify(
    $this->createHtmlConfig(array_merge(array_filter([
        'Cache.SerializerPath' => $serializerPath,
    ]), $config))
);
```

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

### Interact with FilesystemDefinitionCache

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Directly interact with the cache by retrieving or flushing definitions using the FilesystemDefinitionCache class.

```php
use Stevebauman\Purify\Cache\FilesystemDefinitionCache;
use Illuminate\Support\Facades\Storage;
use HTMLPurifier_Config;

$cache = new FilesystemDefinitionCache('HTML');

$config = HTMLPurifier_Config::createDefault();
$config->set('Cache.SerializerPath', 'purify');

var_dump($cache->get($config)); // false (nothing stored yet)
$cache->flush($config);         // removes all non-hidden .ser files under purify/HTML/
```

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

### Sanitize on get with attribute mutator

Source: https://github.com/stevebauman/purify/blob/master/README.md

Implements the same on-get sanitization manually via an Eloquent attribute mutator, calling Purify::clean() on the attribute value.

```php
use Stevebauman\Purify\Facades\Purify;

class Post extends Model
{
    public function getContentAttribute($value)
    {
        return Purify::clean($value);
    }
}
```

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

### add($def, $config)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Adds a definition object to the cache. Returns void if the definition type does not match the cache type, false if the key already exists, otherwise the result of Cache::put.

```APIDOC
## add($def, $config)

### Description
Adds a definition object to the cache. Returns void if the definition type does not match the cache type, false if the key already exists, otherwise the result of Cache::put.

### Method
add

### Signature
public function add($def, $config)

### Parameters
- **$def** (HTMLPurifier_Definition) - Required - The definition object to cache.
- **$config** (HTMLPurifier_Config) - Required - The configuration object.

### Return Value
- **bool|void** - Returns void on type mismatch, false if key exists, otherwise the result of Cache::put (bool).
```

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

### register() method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-service-provider.md

Defines the register method with a docblock. It is called during provider registration.

```php
/**
 * Register the service provider.
 *
 * @return void
 */
public function register()
```

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

### Configure serializer with FilesystemDefinitionCache in config/purify.php

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Use this configuration to set the FilesystemDefinitionCache as the cache for the serializer. The disk is resolved at construction time via config('purify.serializer.disk').

```php
'serializer' => [
    'disk' => env('FILESYSTEM_DISK', 'local'),
    'path' => 'purify',
    'cache' => \Stevebauman\Purify\Cache\FilesystemDefinitionCache::class,
],
```

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

### get($model, $key, $value, $attributes)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

Purifies the given model attribute value. Returns null if the value is null; otherwise, applies Purify configuration to clean the value, including arrays.

```APIDOC
## PurifyHtmlOnGet::get

### Description
Purifies the given model attribute value on retrieval. If the raw value is null, returns null without attempting purification. Otherwise, uses the configured Purify settings to clean the value, which may return a string, array, or null.

### Method
`get($model, $key, $value, $attributes)`

### Parameters
- `$model` (Illuminate\Database\Eloquent\Model) - Required - The model being accessed.
- `$key` (string) - Required - The attribute key.
- `$value` (mixed) - Required - The raw stored value (may be null).
- `$attributes` (array) - Required - All raw model attributes.

### Throws
- `InvalidArgumentException` - When the configured config set name is undefined.

### Returns
- `string|array|null` - The purified value, or null if the input value is null.

### Example
```php
public function get($model, $key, $value, $attributes)
{
    if (is_null($value)) {
        return null;
    }

    return Purify::config($this->config)->clean($value);
}
```
```

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

### Clean a String with Purify::clean

Source: https://github.com/stevebauman/purify/blob/master/README.md

Cleans a single string input using the Purify facade. The example shows that the script tag and style/class attributes are removed, leaving only '<p>Test</p>'.

```php
use Stevebauman\Purify\Facades\Purify;

$input = '<script>alert("Harmful Script");</script> <p style="border:1px solid black" class="text-gray-700">Test</p>';

// Returns '<p>Test</p>'
$cleaned = Purify::clean($input);
```

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

### Run purify:clear with filesystem serializer

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/clear-command.md

Executes the command when the filesystem serializer is configured. The output confirms the filesystem cache was cleared.

```shell
php artisan purify:clear
# HTML Purifier serializer filesystem cache cleared successfully.
```

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

### Publish Purify Configuration

Source: https://github.com/stevebauman/purify/blob/master/README.md

Publishes the configuration file for Purify using the Artisan command.

```bash
php artisan vendor:publish --provider="Stevebauman\Purify\PurifyServiceProvider"
```

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

### Purify::config() with inline configuration

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Demonstrates passing an inline configuration array directly to the purifier, which creates a unique runtime configuration set.

```php
use Stevebauman\Purify\Facades\Purify;

$cleaned = Purify::config(['HTML.Allowed' => 'div,b,a[href]'])->clean($input);
```

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

### Configure Html5Definition as default definitions

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/html5-definition.md

Sets the 'definitions' configuration key to use the built-in Html5Definition class, which is the shipped default in config/purify.php.

```php
'definitions' => Html5Definition::class,
```

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

### Clean with Dynamic Configuration

Source: https://github.com/stevebauman/purify/blob/master/README.md

Uses a custom configuration array for a single input. Note that the configuration passed to the config method is not merged with the default configuration.

```php
use Stevebauman\Purify\Facades\Purify;

$config = ['HTML.Allowed' => 'div,b,a[href]'];

$cleaned = Purify::config($config)->clean($input);
```

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

### Caster::__construct

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

Documentation for the abstract Caster base class constructor.

```APIDOC
## Caster (abstract base)

### Description
Abstract base class for HTML purification casts. Stores the name of the config set to use.

### Constructor

```php
public function __construct($config = null)
```

#### Parameters
- **$config** (string|null) - Optional - The name of a config set in `purify.configs` (or an inline array key). `null` means "use the default config set" (`purify.default`).

### Behavior
Stores `$this->config = $config`.

### Usage
This constructor is how Laravel passes cast parameters: declaring a cast as `PurifyHtmlOnGet::class.':other'` makes Laravel instantiate the cast with `$config = 'other'`.
```

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

### Purify::extend() custom driver registration

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Demonstrates registering a custom driver using the extend method, which allows for custom purification logic.

```php
use Stevebauman\Purify\Facades\Purify;
use Stevebauman\Purify\Purify;

Purify::extend('custom', function ($app) {
    // Return any object with a clean() method — the source does not type-check the return.
    return new class {
        public function clean($input) { return 'custom!'; }
    };
});

echo Purify::driver('custom')->clean('<b>x</b>'); // custom!
```

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

### Run purify:clear with default cache-store serializer

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/clear-command.md

Executes the command with the default serializer, which uses the cache store. The output confirms the cache was cleared.

```shell
php artisan purify:clear
# HTML Purifier serializer cache cleared successfully.
```

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

### flush($config) method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Clears all objects from the cache by iterating through the type directory and deleting non-hidden files.

```php
/**
 * Clears all objects from cache.
 *
 * @param \HTMLPurifier_Config $config
 *
 * @return bool
 */
public function flush($config)
```

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

### generateBaseDirectoryPath($config) implementation

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Retrieves the base directory path from the Cache.SerializerPath configuration, defaulting to '/' if null.

```php
protected function generateBaseDirectoryPath($config)
{
    $base = $config->get('Cache.SerializerPath');

    return is_null($base) ? '/' : $base;
}
```

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

### Purify::config() named configuration set

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Demonstrates using a specific named configuration set defined in the application's purify.php configuration file.

```php
use Stevebauman\Purify\Facades\Purify;

// Requires a 'comments' set in config/purify.php 'configs'
$purify = Purify::config('comments')->clean(request('content'));
```

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

### Paste keys into configs.default array

Source: https://github.com/stevebauman/purify/blob/master/README.md

Paste the copied keys into the configs.default array of the newly published config/purify.php file, overwriting the current values. The diff shows the additions.

```diff
'configs' => [
    'default' => [
        'Core.Encoding' => 'utf-8',
        'HTML.Doctype' => 'HTML 4.01 Transitional',
+       'HTML.Allowed' => 'h1,h2,h3,h4,h5,h6,b,strong,i,em,a[href|title],ul,ol,li,p[style],br,span,img[width|height|alt|src]',
+       'HTML.ForbiddenElements' => '',
+       'CSS.AllowedProperties' => 'font,font-size,font-weight,font-style,font-family,text-decoration,padding-left,color,background-color,text-align',
+       'AutoFormat.AutoParagraph' => false,
+       'AutoFormat.RemoveEmpty' => false,
    ],
],
```

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

### set($def, $config)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Unconditionally saves a definition object to the cache. Returns void on type mismatch, otherwise the result of Cache::put.

```APIDOC
## set($def, $config)

### Description
Unconditionally saves a definition object to the cache. Returns void on type mismatch, otherwise the result of Cache::put.

### Method
set

### Signature
public function set($def, $config)

### Parameters
- **$def** (HTMLPurifier_Definition) - Required - The definition object to cache.
- **$config** (HTMLPurifier_Config) - Required - The configuration object.

### Return Value
- **bool|void** - Returns void on type mismatch, otherwise the result of Cache::put (bool).
```

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

### Create and register a custom HTML definition

Source: https://github.com/stevebauman/purify/blob/master/README.md

Create a custom HTML definition class implementing the Definition interface and reference it in the 'definitions' key of config/purify.php. The apply method receives an HTMLPurifier_HTMLDefinition instance for customization.

```php
namespace App;

use HTMLPurifier_HTMLDefinition;
use Stevebauman\Purify\Definitions\Definition;

class CustomDefinition implements Definition
{
    /**
     * Apply rules to the HTML Purifier definition.
     *
     * @param HTMLPurifier_HTMLDefinition $definition
     *
     * @return void
     */
    public static function apply(HTMLPurifier_HTMLDefinition $definition)
    {
        // Customize the HTML purifier definition.
    }
}
```

```php
// config/purify.php

'definitions' => \App\CustomDefinitions::class,
```

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

### flush($config)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Clears all objects from cache. Returns the result of Cache::clear, which wipes the entire cache store.

```APIDOC
## flush($config)

### Description
Clears all objects from cache. Returns the result of Cache::clear, which wipes the entire cache store.

### Method
flush

### Signature
public function flush($config)

### Parameters
- **$config** (HTMLPurifier_Config) - Required - The configuration object.

### Return Value
- **bool** - The result of Cache::clear.
```

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

### Error handling for invalid config name

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/facade.md

Shows how to catch an InvalidArgumentException when attempting to use a configuration set that is not defined.

```php
use Stevebauman\Purify\Facades\Purify;

try {
    Purify::config('missing-set');
} catch (\InvalidArgumentException $e) {
    // "Purify config [missing-set] not defined."
}
```

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

### Clean Using Named Configuration

Source: https://github.com/stevebauman/purify/blob/master/README.md

Uses the named 'comments' configuration set to clean user input from a request. This demonstrates how to apply a specific configuration by its name.

```php
use Stevebauman\Purify\Facades\Purify;

$cleanedContent = Purify::config('comments')->clean(request('content'));
```

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

### cleanup($config)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Clears all expired (older version or revision) objects from cache. Deletes the key when isOld returns true, otherwise returns true without touching storage.

```APIDOC
## cleanup($config)

### Description
Clears all expired (older version or revision) objects from cache. Deletes the key when isOld returns true, otherwise returns true without touching storage.

### Method
cleanup

### Signature
public function cleanup($config)

### Parameters
- **$config** (HTMLPurifier_Config) - Required - The configuration object.

### Return Value
- **bool** - Returns true if key is not old, otherwise the result of Cache::delete.
```

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

### Named config set via cast parameter

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

Demonstrates using a named config set from config/purify.php by appending ':other' to the cast class string.

```php
class Post extends Model
{
    protected function casts()
    {
        return [
            // Uses the 'other' set from config/purify.php 'configs'
            'content' => PurifyHtmlOnGet::class.':other',
        ];
    }
}
```

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

### Serializer cache-store configuration array (purify.serializer)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/configuration.md

PHP configuration array for the HTMLPurifier definition cache. The `driver` key defaults to `env('CACHE_STORE', env('CACHE_DRIVER', 'file'))` and is resolved via `Cache::driver()`. The `cache` key defaults to `\Stevebauman\Purify\Cache\CacheDefinitionCache::class`. This array is passed to Laravel's config.

```php
'serializer' => [
    'driver' => env('CACHE_STORE', env('CACHE_DRIVER', 'file')),
    'cache' => \Stevebauman\Purify\Cache\CacheDefinitionCache::class,
],
```

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

### config()

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Convenience alias for driver(). Resolves a Purify instance using a config set name, an inline config array, or the default set.

```APIDOC
## config()

### Description
Convenience alias for `driver()`. Resolves a Purify instance using a config set name, an inline config array, or the default set.

### Method
`config()`

### Signature
```php
public function config($config = null)
```

### Parameters
- **$config** (`string|array|null`) - Optional - A config set name, an inline config array, or `null` for the default set (`purify.default`).

### Returns
- **Purify** - The resolved purifier instance (delegates to `driver($config)`).

### Throws
- **InvalidArgumentException** - When the name is not defined as a config set.

### Example - default config
```php
use Stevebauman\Purify\Facades\Purify;

$purify = Purify::config(); // Uses config: purify.default
echo $purify->clean('<b>x</b>');
```

### Example - named config set
```php
use Stevebauman\Purify\Facades\Purify;

// Requires a 'comments' set in config/purify.php 'configs'
$purify = Purify::config('comments')->clean(request('content'));
```
```

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

### Path generator method signatures

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Public methods used for generating file and directory paths for the cache.

```php
public function generateFilePath($config)       // src/...:192
public function generateDirectoryPath($config)  // src/...:208  (no trailing slash)
public function generateBaseDirectoryPath($config) // src/...:223
```

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

### Handle missing disk errors

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/filesystem-definition-cache.md

Catch InvalidArgumentException when an undefined disk is provided to the cache.

```php
use Stevebauman\Purify\Cache\FilesystemDefinitionCache;

config()->set('purify.serializer.disk', 'undefined-disk');

try {
    $cache = new FilesystemDefinitionCache('HTML'); // Storage::disk() throws
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // Disk [undefined-disk] does not have a configured driver.
}
```

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

### Laravel auto-discovery configuration in composer.json

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/README.md

Registers the package's service provider and facade alias via Laravel package auto-discovery. The 'extra.laravel' key in composer.json declares the provider and alias so the package is automatically discovered.

```json
"extra": {
    "laravel": {
        "providers": [
            "Stevebauman\\Purify\\PurifyServiceProvider"
        ],
        "aliases": {
            "Purify": "Stevebauman\\Purify\\Facades\\Purify"
        }
    }
}
```

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

### createHtmlConfig method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Protected method that assembles the HTMLPurifier_Config. It creates the config, sets DefinitionID, DefinitionRev, Cache.DefinitionImpl, and applies raw HTML and CSS definitions if configured.

```php
protected function createHtmlConfig($config)
```

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

### set($model, $key, $value, $attributes)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/casts.md

Prepares the value for storage. Returns the raw value unmodified, so purification only occurs on read, not on write.

```APIDOC
## PurifyHtmlOnGet::set

### Description
Prepares the value for storage. This method returns the raw value unchanged, meaning the stored data is never purified by this cast. Purification is only performed on read via the get method.

### Method
`set($model, $key, $value, $attributes)`

### Parameters
- `$model` (Illuminate\Database\Eloquent\Model) - Required - The model being accessed.
- `$key` (string) - Required - The attribute key.
- `$value` (mixed) - Required - The raw value to be stored.
- `$attributes` (array) - Required - All raw model attributes.

### Returns
- `array|string|null` - The raw value, unmodified.

### Example
```php
public function set($model, $key, $value, $attributes)
{
    return $value;
}
```
```

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

### CacheDefinitionCache::add() method

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Adds a definition object to the cache. Returns void on type mismatch, false if the key already exists, otherwise the result of Cache::put($key, encode($def)).

```php
/**
 * Adds a definition object to the cache.
 *
 * @param HTMLPurifier_Definition $def
 * @param \HTMLPurifier_Config    $config
 *
 * @return bool|void
 */
public function add($def, $config)
```

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

### Register video and source elements

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/html5-definition.md

Registers video and source elements with attributes for media playback. Video supports src, type, width, height, poster, preload, and controls; source supports src and type.

```php
$definition->addElement('video', 'Block', 'Optional: (source, Flow) | (Flow, source) | Flow', 'Common', [
    'src' => 'URI',
    'type' => 'Text',
    'width' => 'Length',
    'height' => 'Length',
    'poster' => 'URI',
    'preload' => 'Enum#auto,metadata,none',
    'controls' => 'Bool',
]);
$definition->addElement('source', 'Block', 'Flow', 'Common', [
    'src' => 'URI',
    'type' => 'Text',
]);
```

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

### clean() method implementation

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify.md

The internal implementation of the clean() method showing the dispatch between array and string purification.

```php
public function clean($input)
{
    return is_array($input)
        ? $this->purifier->purifyArray($input)
        : $this->purifier->purify($input);
}
```

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

### Registering a Custom Definition in Configuration

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/types.md

How to register the custom definition class within the purify configuration file.

```php
// config/purify.php
'definitions' => \App\CustomDefinition::class,
```

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

### Run purify:clear when caching is disabled

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/clear-command.md

Executes the command when the serializer is set to null. The output indicates that the serializer path is not defined.

```shell
php artisan purify:clear
# Purifier serializer path is not defined. Did you set it to null or forget to publish the configuration?
```

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

### replace($def, $config)

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Replaces an object in the cache. Returns void on type mismatch, false if the key does not exist, otherwise the result of Cache::put.

```APIDOC
## replace($def, $config)

### Description
Replaces an object in the cache. Returns void on type mismatch, false if the key does not exist, otherwise the result of Cache::put.

### Method
replace

### Signature
public function replace($def, $config)

### Parameters
- **$def** (HTMLPurifier_Definition) - Required - The definition object to cache.
- **$config** (HTMLPurifier_Config) - Required - The configuration object.

### Return Value
- **bool|void** - Returns void on type mismatch, false if key does not exist, otherwise the result of Cache::put (bool).
```

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

### apply() method signature and docblock

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/html5-definition.md

The static apply() method that receives an HTMLPurifier_HTMLDefinition and applies HTML5 rules. It returns void and does not declare any thrown exceptions.

```php
/**
 * Apply rules to the HTML Purifier definition.
 *
 * @param HTMLPurifier_HTMLDefinition $definition
 *
 * @return void
 */
public static function apply(HTMLPurifier_HTMLDefinition $definition)
```

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

### ClearCommand handle method with decision logic

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/clear-command.md

The `handle` method of `ClearCommand` checks the `purify.serializer` config, then clears the cache based on the configured cache class. It returns error or info messages accordingly.

```php
public function handle(Repository $config)
{
    if (empty($serializer = $config->get('purify.serializer'))) {
        return $this->error(
            'Purifier serializer path is not defined. Did you set it to null or forget to publish the configuration?'
        );
    }

    /** @var class-string $cache */
    $cache = $serializer['cache'];

    if (is_a($cache, FilesystemDefinitionCache::class, true)) {
        $disk = Storage::disk($serializer['disk']);

        $disk->deleteDirectory($serializer['path']);

        $disk->makeDirectory($serializer['path']);

        return $this->info('HTML Purifier serializer filesystem cache cleared successfully.');
    }

    if (is_a($cache, CacheDefinitionCache::class, true)) {
        $cache = Cache::driver($serializer['driver']);

        $cache->clear();

        return $this->info('HTML Purifier serializer cache cleared successfully.');
    }

    return $this->error(
        sprintf('Unable to determine a clear cache strategy with the given cache instance [%s].', $cache)
    );
}
```

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

### Reconfigure serializer path

Source: https://github.com/stevebauman/purify/blob/master/README.md

If you previously set a unique serializer path via the old Cache.SerializerPath key, reconfigure it using the new serializer configuration key.

```php
'serializer' => storage_path('app/purify'),
```

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

### Copy settings array excluding old keys

Source: https://github.com/stevebauman/purify/blob/master/README.md

Copy the settings array from the published config/purify.php file, removing the keys 'HTML.DocType', 'Core.Encoding', and 'Cache.SerializerPath'. The diff shows the old keys removed and the new keys to add.

```diff
'settings' => [
-   'Core.Encoding' => 'utf-8',
-   'Cache.SerializerPath' => storage_path('app/purify'),
-   'HTML.Doctype' => 'XHTML 1.0 Strict',
+   'HTML.Allowed' => 'h1,h2,h3,h4,h5,h6,b,strong,i,em,a[href|title],ul,ol,li,p[style],br,span,img[width|height|alt|src]',
+   'HTML.ForbiddenElements' => '',
+   'CSS.AllowedProperties' => 'font,font-size,font-weight,font-style,font-family,text-decoration,padding-left,color,background-color,text-align',
+   'AutoFormat.AutoParagraph' => false,
+   'AutoFormat.RemoveEmpty' => false,
],
```

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

### CacheDefinitionCache::get() method

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Retrieves a definition object from the cache. Returns false when the key is missing, otherwise the decoded definition. Note: for a stale key whose stored value was false, decode of false would run @unserialize(false); no guard exists.

```php
/**
 * Retrieves a definition object from the cache.
 *
 * @param \HTMLPurifier_Config $config
 *
 * @return bool|HTMLPurifier_Definition
 */
public function get($config)
```

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

### resolveSerializerPath method signature

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/purify-manager.md

Protected method that returns the serializer path for a config name, or false if the serializer path is empty.

```php
protected function resolveSerializerPath($name)
```

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

### Configure CacheDefinitionCache in config/purify.php

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Default shipped configuration for the Purify serializer. Sets the cache driver from the CACHE_STORE or CACHE_DRIVER environment variable (falling back to 'file') and uses the CacheDefinitionCache class.

```php
// config/purify.php
'serializer' => [
    'driver' => env('CACHE_STORE', env('CACHE_DRIVER', 'file')),
    'cache' => \Stevebauman\Purify\Cache\CacheDefinitionCache::class,
],
```

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

### Class declaration for Html5Definition

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/html5-definition.md

Declares the Html5Definition class implementing the Definition interface. It has no constructor or properties; all logic is in the static apply() method.

```php
class Html5Definition implements Definition
```

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

### CacheDefinitionCache constructor

Source: https://github.com/stevebauman/purify/blob/master/_autodocs/api-reference/cache-definition-cache.md

Constructor for CacheDefinitionCache. Accepts the definition type ('HTML' or 'CSS') and passes it to the parent HTMLPurifier_DefinitionCache constructor. The cache store is set from config('purify.serializer.driver') using Laravel's Cache::driver().

```php
public function __construct($type)
```
Tokens:
Raw