Merge pull request #1 from nswdpc/feat-htmlpurifier

Change: switch to htmlpurifier for content sanitisation

.gitattributes

@@ -4,7 +4,8 @@
 /.gitattributes export-ignore
 /.gitignore export-ignore
 /.php_cs.dist
-/.phpcs.xml.dist
-/.phpunit.xml.dist
+/phpcs.xml.dist
+/phpstan.neon.dist
+/phpunit.xml.dist
 /.waratah export-ignore
 /README.md export-ignore

.gitignore

@@ -1,3 +1,8 @@
 /client/node_modules
 /vendor/
+/resources/
+/assets/
 .DS_Store
+/.php_cs.cache
+/composer.lock
+/silverstripe-cache/

CONTRIBUTING.md

@@ -1,14 +1,19 @@
 # Contributing
+
+For simplicity, our contribution process follows the relevant Silverstripe documents.
+
+## Guidelines
+
 - Maintenance on this module is a shared effort of those who use it
 - To contribute improvements to the code, ensure you raise a pull request and discuss with the module maintainers
-- Please follow the SilverStripe [code contribution guidelines](https://docs.silverstripe.org/en/contributing/code/) and [Module Standard](https://docs.silverstripe.org/en/developer_guides/extending/modules/#module-standard)
+- Please follow the Silverstripe [code contribution guidelines](https://docs.silverstripe.org/en/contributing/code/) and [Module Standard](https://docs.silverstripe.org/en/developer_guides/extending/modules/#module-standard)
 - Supply documentation that follows the [GitHub Flavored Markdown](https://help.github.com/articles/markdown-basics/) conventions
-- When having discussions about this module in issues or pull request please adhere to the [SilverStripe Community Code of Conduct](https://docs.silverstripe.org/en/contributing/code_of_conduct/)
-
+- When having discussions about this module in issues or pull request please adhere to the [Silverstripe Community Code of Conduct](https://docs.silverstripe.org/en/contributing/code_of_conduct/)
 
 ## Contributor license agreement
-By supplying code to this module in patches, tickets and pull requests, you agree to assign copyright 
-of that code to MODULE_COPYRIGHT_HOLDER_HERE., on the condition that these code changes are released under the 
-same BSD license as the original module. We ask for this so that the ownership in the license is clear 
-and unambiguous. By releasing this code under a permissive license such as BSD, this copyright assignment 
-won't prevent you from using the code in any way you see fit.
+
+By supplying code to this module in patches, tickets and pull requests, you agree to assign copyright  of that code to New South Wales Department of Premier & Cabinet, on the condition that these code changes are released under the same BSD license as the original module.
+
+We ask for this so that the ownership in the license is clear and unambiguous.
+
+By releasing this code under a permissive license such as BSD, this copyright assignment won't prevent you from using the code in any way you see fit.

README.md

@@ -2,47 +2,42 @@
 
 Decorate textarea fields with the [Trumbowyg](https://github.com/Alex-D/Trumbowyg) editor.
 
-Trumbowyg is "A lightweight and amazing WYSIWYG JavaScript editor - 20kB only (8kB gzip)"
-
-It is useful for gathering content where some form of formatting in HTML is required.
-
 This module supports:
-+ content sanitising of submitted content (on the client side and server side)
++ content sanitising of submitted content on the client side using Trumbowyg configuration rules and server side using [HTMLPurifier](https://github.com/ezyang/htmlpurifier))
 + restricted feature set by default ([see documentation](./docs/en/001_index.md))
 
-The module will not support:
+## Use cases
+
+This editor field is useful for gathering content where some form of formatting in HTML is required. It is not intended for use in the administration area (although PRs are welcome for that, for example a restricted content editing field)
+
+As the goal is only a restricted feature set for simple content submissions, the module will not support:
+
 + file uploads
 + image uploads
 + image insertion
 
-Please use dedicated upload fields for that purpose.
-
-This field is not intended for use in the administration area (although PRs are welcome for that)
+Please use dedicated upload fields for handling file uploads.
 
 ## Requirements
 
+Per [composer.json](/composer.json):
+
 + silverstripe/framework ^4
-+ php-xml extension
-+ Trumbowyg depends on jQuery (latest at time of release)
++ jQuery 3.6.0
+
+The field pulls in required Trumbowyg JS and CSS assets from [cdnjs.com](https://cdnjs.com) along with their respective Sub Resource Integrity (SRI) hashes.
 
-The field pulls in required JS and CSS assets from [cdnjs.com](https://cdnjs.com) along with their respective Sub Resource Integrity hashes.
+If you wish to use your own jQuery, set the  `TrumboywgEditorField.use_own_jquery` configuration value to `true` in your project configuration.
 
 ## Installation
 
-```bash
+```shell
 composer require nswdpc/silverstripe-trumbowyg
 ```
 
 ## Usage
 
-```php
-use NSWDPC\Utilities\Trumbowyg\TrumboywgEditorField;
-
-// TrumboywgEditorField extends TextareaField
-$field = TrumboywgEditorField::create('MyEditorField', 'Write something')
-            ->setDescription("This is a description")
-            ->setRightTitle("This is a right title");
-```
+See [the basic example](./docs/en/01_index.md#basic-example)
 
 ## License
 

composer.json

@@ -16,12 +16,31 @@
             "role": "Developer"
         }
     ],
+    "autoload": {
+         "psr-4": {
+             "NSWDPC\\Utilities\\Trumbowyg\\": [
+                 "src/"
+             ],
+             "NSWDPC\\Utilities\\Trumbowyg\\Tests\\": [
+                 "tests/"
+             ]
+         }
+    },
+    "extra" : {
+        "expose" : [
+            "client/static"
+        ]
+    },
     "require": {
         "silverstripe/framework" : "^4",
-        "ext-xml" : "*"
+        "ezyang/htmlpurifier" : "^4.13"
     },
     "require-dev": {
-        "phpunit/phpunit": "^5.7 | ^7",
-        "squizlabs/php_codesniffer": "^3.0"
+        "phpunit/phpunit": "^5.7",
+        "squizlabs/php_codesniffer": "^3.0",
+        "friendsofphp/php-cs-fixer": "^2.18",
+        "codeception/codeception" : "^2.5 | ^3 | ^4",
+        "silverstripe/sqlite3": "^2",
+        "symbiote/silverstripe-phpstan": "^4"
     }
 }

docs/en/001_index.md

@@ -24,8 +24,6 @@ By default the following tags are allowed in the editor (see _config/config.yml)
 - strong
 - em
 - br
-- h1
-- h2
 - h3
 - h4
 - h5
@@ -37,7 +35,7 @@ By default the following tags are allowed in the editor (see _config/config.yml)
 - strike
 ```
 
-These are also used when saving the field value in the backend.
+Only the `href` attribute is allowed (for links), with http or https schemes.
 
 If no configuration value `tagsToKeep` is available or it is empty, a default set is used. The fallback condition is to restrict to '<p>' tags only.
 
@@ -55,8 +53,7 @@ $options = [
     "autogrow" => true, // allow the text edit zone to extend
     "buttons" => [
         [ "undo", "redo" ],
-        [ "formatting" ], // basic formatting
-        [ "strong", "em" ], // semantic strong and emphasis
+        [ "p","h3", "h4", "h5", "strong", "em" ], // basic formatting
         [ "link", "" ], // support adding <a> links
         [ "unorderedList", "orderedList" ], // ul and ol
         [ "removeformat" ], // clear all formatting to assist with removing cruft
@@ -68,8 +65,86 @@ $options = [
 ];
 ```
 
+## Basic example
+
+In this example, we are collecting a submission in basic HTML from a `UserSubmissionController`. The field setup is the same as a standard `TextareaField`
+
+```php
+namespace MyApp;
+
+
+use NSWDPC\Utilities\Trumbowyg\TrumboywgEditorField;
+use SilverStripe\CMS\Controllers\ContentController;
+use SilverStripe\Forms\Form;
+use SilverStripe\Forms\Fieldlist;
+use SilverStripe\Forms\FormAction;
+
+class UserSubmissionController extends ContentController
+{
+    /**
+     * @var array
+     */
+    private static $allowed_actions = [
+        'UserEditForm' => true,
+    ];
+
+    /**
+     * Return the form for accepting data
+     */
+    public function UserEditForm() : Form {
+        return Form::create(
+            $this,
+            'UserEditForm',
+            Fieldlist::create(
+                TrumboywgEditorField::create(
+                    'UserProvidedContent', // field name
+                    'Write something' // title
+                )->setDescription(
+                    // optional
+                    "This is a description"
+                )->setRightTitle(
+                    // optional
+                    "This is a right title"
+                )
+            ),
+            Fieldlist::create(
+                FormAction::create(
+                    'doSubmission'
+                )
+            )
+        );
+    }
+
+    /**
+     * Handle the submitted content
+     */
+    public function doSubmission($data, $form) {
+        if(empty($data['UserProvidedContent'])) {
+            // error - no content
+        }
+        // UserProvidedContent will be return via
+        // TrumboywgEditorField::dataValue()
+        $sanitised = $data['UserProvidedContent'];
+        // save the content somewhere
+    }
+}
+```
+
+In your template, render the form:
+
+```template
+<% if $UserEditForm %>
+    <h1>Provide some information</h1>
+    <section>
+        {$UserEditForm}
+    </section>
+<% end_if %>
+```
+
 ## Modifying the configuration
 
-Be aware of cross-site scripting issues if certain tags are configured to be allowed. Good resources are:
+Be aware of cross-site scripting issues if certain tags and/or attributes are configured to be allowed.
+
+Good resources are:
 + https://html5sec.org/
 + https://owasp.org/www-community/xss-filter-evasion-cheatsheet

phpstan.neon.dist

@@ -0,0 +1,6 @@
+parameters:
+    autoload_directories:
+        - src
+        - tests
+includes:
+    - vendor/symbiote/silverstripe-phpstan/phpstan.neon

phpunit.xml.dist

@@ -1,7 +1,30 @@
-<phpunit bootstrap="vendor/silverstripe/cms/tests/bootstrap.php" colors="true">
+<phpunit
+    bootstrap="vendor/silverstripe/framework/tests/bootstrap.php"
+    colors="true"
+    backupGlobals="false"
+    backupStaticAttributes="false"
+    convertErrorsToExceptions="true"
+    convertNoticesToExceptions="true"
+    convertWarningsToExceptions="true"
+    processIsolation="false"
+    stopOnError="false"
+    stopOnFailure="false"
+    stopOnIncomplete="false"
+    stopOnSkipped="false"
+    syntaxCheck="false"
+    verbose="true"
+    strict="false">
+
     <testsuite name="nswdpc/silverstripe-trumbowyg">
         <directory>tests/</directory>
     </testsuite>
+
+    <groups>
+        <exclude>
+            <group>sanitychecks</group>
+        </exclude>
+    </groups>
+
     <filter>
         <whitelist addUncoveredFilesFromWhitelist="true">
             <directory suffix=".php">src/</directory>
@@ -10,4 +33,18 @@
             </exclude>
         </whitelist>
     </filter>
+
+    <php>
+        <!-- use envvarset in your YML files -->
+        <env name="SS_TEST" value="1"/>
+        <var name="runningtests" value="true"/>
+        <!-- sqlite3 for testing module -->
+        <env name="SS_DATABASE_CLASS" value="SQLite3Database"/>
+        <env name="SS_DATABASE_NAME" value="SS_trumbowyg_testdb"/>
+        <env name="SS_DATABASE_SERVER" value="none"/>
+        <env name="SS_DATABASE_USERNAME" value="none"/>
+        <env name="SS_DATABASE_PASSWORD" value="none"/>
+        <env name="SS_SQLITE_DATABASE_PATH" value=":memory:"/>
+    </php>
+
 </phpunit>