diff --git a/README.md b/README.md index 96318ba..fb50778 100644 --- a/README.md +++ b/README.md @@ -344,6 +344,52 @@ class TrixPurifierDefinitions implements Definition } ``` + +#### 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`: + +```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, + ); + } +} +``` + +Then, reference this class in the `config/purify.php` file in the `css-definitions` key: + +```php +// config/purify.php + +'css-definitions' => \App\CustomCssDefinition::class, +``` + +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: diff --git a/config/purify.php b/config/purify.php index 5977b03..15ee72a 100644 --- a/config/purify.php +++ b/config/purify.php @@ -70,6 +70,26 @@ 'definitions' => Html5Definition::class, + /* + |-------------------------------------------------------------------------- + | HTMLPurifier CSS definitions + |-------------------------------------------------------------------------- + | + | Here you may specify a class that augments the CSS definitions used by + | HTMLPurifier. When specifying a custom class, make sure it implements + | the interface: + | + | \Stevebauman\Purify\Definitions\CssDefinition + | + | Note that these definitions are applied to every Purifier instance. + | + | CSS should be extending $definition->info['css-attribute'] = values + | See HTMLPurifier_CSSDefinition for further explanation + | + */ + + 'css-definitions' => null, + /* |-------------------------------------------------------------------------- | Serializer diff --git a/src/Definitions/CssDefinition.php b/src/Definitions/CssDefinition.php new file mode 100644 index 0000000..6863d60 --- /dev/null +++ b/src/Definitions/CssDefinition.php @@ -0,0 +1,17 @@ +getCSSDefinition()) { + $definitionsClass = $this->config->get('purify.css-definitions'); + + if ($definitionsClass && is_a($definitionsClass, CssDefinition::class, true)) { + $definitionsClass::apply($definition); + } + } + return $htmlConfig; } } diff --git a/tests/PurifyTest.php b/tests/PurifyTest.php index e709ff1..7572b68 100644 --- a/tests/PurifyTest.php +++ b/tests/PurifyTest.php @@ -2,9 +2,11 @@ namespace Stevebauman\Purify\Tests; +use HTMLPurifier_CSSDefinition; use HTMLPurifier_HTMLDefinition; use Illuminate\Support\Facades\File; use Stevebauman\Purify\Cache\CacheDefinitionCache; +use Stevebauman\Purify\Definitions\CssDefinition; use Stevebauman\Purify\Definitions\Definition; use Stevebauman\Purify\Facades\Purify; use Stevebauman\Purify\PurifyServiceProvider; @@ -131,6 +133,36 @@ public function test_custom_definitions_are_applied() Purify::config(['HTML.Allowed' => 'span[class]'])->clean('
') ); } + + public function test_custom_css_definitions_are_applied() + { + $this->app['config']->set('purify.css-definitions', FooCssDefinition::class); + + $this->assertEquals( + 'Test
', + Purify::clean('Test
') + ); + + $this->assertEquals( + 'Test
', + Purify::clean('Test
') + ); + + $this->assertEquals( + 'Test
', + Purify::clean('Test
') + ); + + $this->assertEquals( + 'Test
', + Purify::clean('Test
') + ); + + $this->assertEquals( + 'Test
', + Purify::clean('Test
') + ); + } } class FooDefinition implements Definition @@ -140,3 +172,14 @@ public static function apply(HTMLPurifier_HTMLDefinition $definition) $definition->addAttribute('span', 'class', 'Enum#foo'); } } + +class FooCssDefinition implements CssDefinition +{ + public static function apply(HTMLPurifier_CSSDefinition $definition) + { + $definition->info['text-align'] = new \HTMLPurifier_AttrDef_Enum( + ['center', 'start', 'end'], + false, + ); + } +}