Upgrade to 3.6.0

kirby/src/Sane/Sane.php

@@ -2,8 +2,9 @@
 
 namespace Kirby\Sane;
 
+use Kirby\Exception\LogicException;
 use Kirby\Exception\NotFoundException;
-use Kirby\Toolkit\F;
+use Kirby\Filesystem\F;
 
 /**
  * The `Sane` class validates that files
@@ -26,8 +27,10 @@ class Sane
      * @var array
      */
     public static $aliases = [
-        'image/svg+xml'   => 'svg',
         'application/xml' => 'xml',
+        'image/svg'       => 'svg',
+        'image/svg+xml'   => 'svg',
+        'text/html'       => 'html',
         'text/xml'        => 'xml',
     ];
 
@@ -37,6 +40,7 @@ class Sane
      * @var array
      */
     public static $handlers = [
+        'html' => 'Kirby\Sane\Html',
         'svg'  => 'Kirby\Sane\Svg',
         'svgz' => 'Kirby\Sane\Svgz',
         'xml'  => 'Kirby\Sane\Xml',
@@ -72,10 +76,68 @@ class Sane
         throw new NotFoundException('Missing handler for type: "' . $type . '"');
     }
 
+    /**
+     * Sanitizes the given string with the specified handler
+     * @since 3.6.0
+     *
+     * @param string $string
+     * @param string $type
+     * @return string
+     */
+    public static function sanitize(string $string, string $type): string
+    {
+        return static::handler($type)->sanitize($string);
+    }
+
+    /**
+     * Sanitizes the contents of a file by overwriting
+     * the file with the sanitized version;
+     * the sane handlers are automatically chosen by
+     * the extension and MIME type if not specified
+     * @since 3.6.0
+     *
+     * @param string $file
+     * @param string|bool $typeLazy Explicit handler type string,
+     *                              `true` for lazy autodetection or
+     *                              `false` for normal autodetection
+     * @return void
+     *
+     * @throws \Kirby\Exception\InvalidArgumentException If the file didn't pass validation
+     * @throws \Kirby\Exception\LogicException If more than one handler applies
+     * @throws \Kirby\Exception\NotFoundException If the handler was not found
+     * @throws \Kirby\Exception\Exception On other errors
+     */
+    public static function sanitizeFile(string $file, $typeLazy = false): void
+    {
+        if (is_string($typeLazy) === true) {
+            static::handler($typeLazy)->sanitizeFile($file);
+            return;
+        }
+
+        // try to find exactly one matching handler
+        $handlers = static::handlersForFile($file, $typeLazy === true);
+        switch (count($handlers)) {
+            case 0:
+                // lazy autodetection didn't find a handler
+                break;
+            case 1:
+                $handlers[0]->sanitizeFile($file);
+                break;
+            default:
+                // more than one matching handler;
+                // sanitizing with all handlers will not leave much in the output
+                $handlerNames = array_map('get_class', $handlers);
+                throw new LogicException(
+                    'Cannot sanitize file as more than one handler applies: ' .
+                    implode(', ', $handlerNames)
+                );
+        }
+    }
+
     /**
      * Validates file contents with the specified handler
      *
-     * @param mixed $string
+     * @param string $string
      * @param string $type
      * @return void
      *
@@ -110,20 +172,38 @@ class Sane
             return;
         }
 
-        $options = [F::extension($file), F::mime($file)];
-
-        // execute all handlers, but each class only once for performance;
-        // filter out all empty options
-        $usedHandlers = [];
-        foreach (array_filter($options) as $option) {
-            $handler      = static::handler($option, $typeLazy === true);
-            $handlerClass = $handler ? get_class($handler) : null;
-
-            if ($handler && in_array($handlerClass, $usedHandlers) === false) {
-                $handler->validateFile($file);
-
-                $usedHandlers[] = $handlerClass;
-            }
+        foreach (static::handlersForFile($file, $typeLazy === true) as $handler) {
+            $handler->validateFile($file);
         }
     }
+
+    /**
+     * Returns all handler objects that apply to the given file based on
+     * file extension and MIME type
+     *
+     * @param string $file
+     * @param bool $lazy If set to `true`, undefined handlers are skipped
+     * @return array<\Kirby\Sane\Handler>
+     */
+    protected static function handlersForFile(string $file, bool $lazy = false): array
+    {
+        $handlers = $handlerClasses = [];
+
+        // all values that can be used for the handler search;
+        // filter out all empty options
+        $options = array_filter([F::extension($file), F::mime($file)]);
+
+        foreach ($options as $option) {
+            $handler      = static::handler($option, $lazy);
+            $handlerClass = $handler ? get_class($handler) : null;
+
+            // ensure that each handler class is only returned once
+            if ($handler && in_array($handlerClass, $handlerClasses) === false) {
+                $handlers[]       = $handler;
+                $handlerClasses[] = $handlerClass;
+            }
+        }
+
+        return $handlers;
+    }
 }