Download the PHP package stevebauman/purify without Composer
On this page you can find all versions of the php package stevebauman/purify. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download stevebauman/purify
More information about stevebauman/purify
Files in stevebauman/purify
Package purify
Short Description An HTML Purifier / Sanitizer for Laravel
License MIT
Informations about the package purify
Purify
A Laravel wrapper for HTMLPurifier by ezyang.
Index
- Requirements
- Installation
- Usage
- Configuration
- Cache
- Practices
- Upgrading from v4 to v5
- Upgrading from v5 to v6
Requirements
- PHP >= 7.4
- Laravel >= 7.0
Installation
To install Purify, run the following command in the root of your project:
Then, publish the configuration file using:
Usage
Cleaning a String
To clean a users input, simply use the clean method:
Cleaning an Array
Need to purify an array of user input? Just pass in an array:
Dynamic Configuration
Need a different configuration for a single input? Pass in a configuration array into the second parameter:
Note: Configuration passed into the second parameter is not merged with your default configuration.
Configuration
Inside the configuration file, multiple HTMLPurifier configuration sets
can be specified, similar to Laravel's built-in database
, mail
and logging
config.
Simply call Purify::config($name)->clean($input)
to use another set of configuration.
For example, if we need to have a separate configuration for a comment system, we
can setup this configuration in the config/purify.php
file:
Then, utilize it anywhere in your application by its name:
For HTMLPurifier configuration documentation, please visit the HTMLPurifier Website:
http://htmlpurifier.org/live/configdoc/plain.html
Cache
After running Purify once, HTMLPurifier will auto-cache your
serialized definitions
into the serializer.cache
definition you have configured in config/purify.php
.
[!Important]
If you have configured Purify to utilize the
CacheDefinitionCache
in theserializer
option, this command will issue aCache::clear()
on the cache driver you have configured it to use.If you have configured Purify to utilize the
FilesystemDefinitionCache
in theserializer
option, this command will clear the directory that you have configured it to store in.It is recommended to setup a unique filesystem path or disk (via
config/filesystems.php
) or cache store (viaconfig/cache.php
) for Purify if you intended to clear the serialized definitions using this command.
If you ever update the definitions
configuration option, you must clear this HTMLPurifier cache.
You may do so via a purify:clear
command:
Disabling Caching
To disable caching all together, you may set the serializer
path to null
:
This will cause your definitions to be serialized upon each application request.
This is especially useful when debugging or tweaking definition files to see immediate results.
[!Important]
Caching is recommended in production environments.
Practices
If you're looking into sanitization, you're likely wanting to sanitize inputted user HTML content that is then stored in your database to be rendered onto your application.
In this scenario, it's likely best practice to sanitize on the way out instead of the on the way in. The database doesn't care what text it contains.
This way you can allow anything to be inserted in the database, and have strong sanization rules on the way out.
To accomplish this, you may use the provided PurifyHtmlOnGet
cast class on your Eloquent model:
Or, implement it yourself via an Eloquent attribute mutator:
You can even configure the configuration that is used when casting by appending it's name to the cast:
This helps tremendously if you change your sanization requirements later down the line, then all rendered content will follow these sanization rules.
If you'd like to purify HTML while setting the value, you can use the inverse PurifyHtmlOnSet
cast instead.
Custom HTML definitions
The HTML.Doctype
configuration option denotes the schema to ultimately abide to.
You may want to extend these schema definitions to support custom elements or
attributes (e.g. <foo>...</foo>
, or <span foo="...">
) by specifying a
custom HTML element "definitions".
Purify ships with additional HTML5 definitions that HTMLPurifier does
not (yet) support of the box (via the Html5Definition
class).
To create your own HTML definition, create a new class and have it implement Definition
:
Then, reference this class in the config/purify.php
file in the definitions
key:
If you'd like to extend the built-in default Html5Definition
, you can apply it to your custom definition:
Basecamp Trix Definition
Here's an example for customizing the definition in order to support Basecamp's Trix WYSIWYG editor (credit to Antonio Primera & Daniel Sun):
Custom CSS definitions
It's possible to override the CSS definitions, this allows you to customize what inline styles you allow and their properties and values. This can help fill in missing values for properties such as text-align, which by default is missing start and end values. You can do this by creating a CSS definition.
To create your own CSS definition, create a new class and have it implement CssDefinition
:
Then, reference this class in the config/purify.php
file in the css-definitions
key:
See the class HTMLPurifier_CSSDefinition in the HTMLPurifier library for other examples of what can be changed.
Upgrading from v4 to v5
To upgrade from v4, install the latest version by running the below command in the root of your project:
Then, navigate into your published config/purify.php
configuration file and
copy the settings
array -- except for the following keys:
HTML.DocType
:Core.Encoding
:Cache.SerializerPath
:
Important: If you've created a unique storage path for
Cache.SerializerPath
, take note of this as well, so you can migrate it into the new configuration file.
Once copied, delete the config/purify.php
file, and run the below command:
Then, inside the newly published config/purify.php
configuration file, paste
the keys (overwriting the current) into the configs.default
array:
If you've created a unique serializer path (previously set via the old Cache.SerializerPath
configuration
key mentioned above), then you may reconfigure this in the new serializer
configuration key:
You're all set!
Upgrading from v5 to v6
In v6, the HTMLPurifier Serializer storage mechanism was updated for Laravel Vapour support, allowing you to store the serialized HTMLPurifier definitions in a Redis cache, or an external filesystem.
To upgrade from v5, install the latest version by running the below command in the root of your project:
Then, navigate into your published config/purify.php
configuration file and
replace the serializer
configuration option with the below:
This will update the syntax used to control the serializer cache mechanism. You may now uncomment
the below serializer
cache definition if you would like to use a Laravel Cache driver
(such as Redis) to store the serialized definitions.
All versions of purify with dependencies
ezyang/htmlpurifier Version ^4.17
illuminate/contracts Version ^7.0|^8.0|^9.0|^10.0|^11.0
illuminate/support Version ^7.0|^8.0|^9.0|^10.0|^11.0