Merge pull request #79 from EPGDigital-MW/master

Add custom CSS Definitions

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:

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

src/Definitions/CssDefinition.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Stevebauman\Purify\Definitions;
+
+use HTMLPurifier_CSSDefinition;
+
+interface CssDefinition
+{
+    /**
+     * Apply rules to the CSS Purifier definition.
+     *
+     * @param HTMLPurifier_CSSDefinition $definition
+     *
+     * @return void
+     */
+    public static function apply(HTMLPurifier_CSSDefinition $definition);
+}

src/PurifyManager.php

@@ -6,6 +6,7 @@
 use Illuminate\Contracts\Container\Container;
 use Illuminate\Support\Manager;
 use InvalidArgumentException;
+use Stevebauman\Purify\Definitions\CssDefinition;
 use Stevebauman\Purify\Definitions\Definition;
 
 class PurifyManager extends Manager
@@ -201,6 +202,14 @@ protected function createHtmlConfig($config)
             }
         }
 
+        if ($definition = $htmlConfig->getCSSDefinition()) {
+            $definitionsClass = $this->config->get('purify.css-definitions');
+
+            if ($definitionsClass && is_a($definitionsClass, CssDefinition::class, true)) {
+                $definitionsClass::apply($definition);
+            }
+        }
+
         return $htmlConfig;
     }
 }

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('<span class="bar">Test</span>')
         );
     }
+
+    public function test_custom_css_definitions_are_applied()
+    {
+        $this->app['config']->set('purify.css-definitions', FooCssDefinition::class);
+
+        $this->assertEquals(
+            '<p>Test</p>',
+            Purify::clean('<p style="text-align:left">Test</p>')
+        );
+
+        $this->assertEquals(
+            '<p>Test</p>',
+            Purify::clean('<p style="text-align:right">Test</p>')
+        );
+
+        $this->assertEquals(
+            '<p style="text-align:center;">Test</p>',
+            Purify::clean('<p style="text-align:center;">Test</p>')
+        );
+
+        $this->assertEquals(
+            '<p style="text-align:start;">Test</p>',
+            Purify::clean('<p style="text-align:start;">Test</p>')
+        );
+
+        $this->assertEquals(
+            '<p style="text-align:end;">Test</p>',
+            Purify::clean('<p style="text-align:end;">Test</p>')
+        );
+    }
 }
 
 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,
+        );
+    }
+}