Add support for normalizing paths on FileProperty

Added:
- Method `FileProperty::normalizePath()` to resolve relative paths while avoiding issues with the `realpath()` function

Changed:
- Method `ImageProperty::processEffectsOne()` to normalize paths

Example:
```
"thumbnail": {
    "type": "image",
    "upload_path": "uploads/thumbnails/src/",
    "effects": [
        {
            "type": "resize",
            "mode": "best_fit",
            "width": 150,
            "height": 150
        },
        {
            "type": "save",
            "copy": "../small/{{filename}}.{{extension}}"
        }
    ]
}
```

src/Charcoal/Property/FileProperty.php

@@ -108,6 +108,13 @@ class FileProperty extends AbstractProperty
      */
     private $filesystem = self::DEFAULT_FILESYSTEM;
 
+    /**
+     * Holds a list of all normalized paths.
+     *
+     * @var string[]
+     */
+    protected static $normalizePathCache = [];
+
     /**
      * @return string
      */
@@ -1283,4 +1290,55 @@ public static function parseUploadedFiles(array $uploadedFiles, callable $filter
 
         return $parsedFiles;
     }
+
+    /**
+     * Normalize a file path string so that it can be checked safely.
+     *
+     * Attempt to avoid invalid encoding bugs by transcoding the path. Then
+     * remove any unnecessary path components including '.', '..' and ''.
+     *
+     * @link https://gist.github.com/thsutton/772287
+     *
+     * @param  string $path     The path to normalise.
+     * @param  string $encoding The name of the path iconv() encoding.
+     * @return string The path, normalised.
+     */
+    public static function normalizePath($path, $encoding = 'UTF-8')
+    {
+        $key = $path;
+
+        if (isset(static::$normalizePathCache[$key])) {
+            return static::$normalizePathCache[$key];
+        }
+
+        // Attempt to avoid path encoding problems.
+        $path = iconv($encoding, $encoding.'//IGNORE//TRANSLIT', $path);
+
+        if (strpos($path, '..') !== false || strpos($path, './') !== false) {
+            // Process the components
+            $parts = explode('/', $path);
+            $safe = [];
+            foreach ($parts as $idx => $part) {
+                if ((empty($part) && !is_numeric($part)) || ($part === '.')) {
+                    continue;
+                } elseif ($part === '..') {
+                    array_pop($safe);
+                    continue;
+                } else {
+                    $safe[] = $part;
+                }
+            }
+
+            // Return the "clean" path
+            $path = implode(DIRECTORY_SEPARATOR, $safe);
+
+            if ($key[0] === '/' && $path[0] !== '/') {
+                $path = '/'.$path;
+            }
+        }
+
+        static::$normalizePathCache[$key] = $path;
+
+        return static::$normalizePathCache[$key];
+    }
 }

src/Charcoal/Property/ImageProperty.php

@@ -497,10 +497,10 @@ private function processEffectsOne($value, array $effects = null, ImageInterface
 
             // @todo Save original file here
             $valuePath = ($isAbsolute ? '' : $basePath);
-            $image->open($valuePath.$value);
+            $image->open(static::normalizePath($valuePath.$value));
             $target = null;
             if ($isAbsolute) {
-                $target = $basePath.$this['uploadPath'].pathinfo($value, PATHINFO_BASENAME);
+                $target = static::normalizePath($basePath.$this['uploadPath'].pathinfo($value, PATHINFO_BASENAME));
             }
 
             foreach ($effects as $fxGroup) {
@@ -545,13 +545,13 @@ private function processEffectsOne($value, array $effects = null, ImageInterface
                     if ($rename || $copy) {
                         if ($copy) {
                             $copy   = $this->renderFileRenamePattern(($target ?: $value), $copy);
-                            $exists = $this->fileExists($basePath.$copy);
+                            $exists = $this->fileExists(static::normalizePath($basePath.$copy));
                             $doCopy = ($copy && ($this['overwrite'] || !$exists));
                         }
 
                         if ($rename) {
                             $value    = $this->renderFileRenamePattern(($target ?: $value), $rename);
-                            $exists   = $this->fileExists($basePath.$value);
+                            $exists   = $this->fileExists(static::normalizePath($basePath.$value));
                             $doRename = ($value && ($this['overwrite'] || !$exists));
                         }
 
@@ -566,20 +566,20 @@ private function processEffectsOne($value, array $effects = null, ImageInterface
 
                         if ($rename || $copy) {
                             if ($doCopy) {
-                                $image->save($valuePath.$copy);
+                                $image->save(static::normalizePath($valuePath.$copy));
                             }
 
                             if ($doRename) {
-                                $image->save($valuePath.$value);
+                                $image->save(static::normalizePath($valuePath.$value));
                             }
                         } else {
-                            $image->save($target ?: $valuePath.$value);
+                            $image->save($target ?: static::normalizePath($valuePath.$value));
                         }
                     }
                 }
                 // reset to default image allow starting effects chains from original image.
                 if ($fxGroup['reset']) {
-                    $image = $image->open($valuePath.$value);
+                    $image = $image->open(static::normalizePath($valuePath.$value));
                 }
             }
         }