[!] Refactor support for values in file properties

Improve support for multilingual/multiple values across various methods of FileProperty.

Validation will now (correctly) log a message if a value (a file) is missing, is unparsable, is a rejected MIME type, or exceeds a maximum file size.

Breaking Changes:
- Removed deprecated accessor methods in favour of get-prefix variants
- Refactored validation methods to focus on values (files) directly
- Moved default MIME types to allow overriding in media-specific properties

Added:
- Option "fallbackFilename" to customize generated filename (defaults to property label)
- Method `hasAcceptedMimetypes()` to check if any custom or fallback MIME types are specified
- Method `getDefaultAcceptedMimetypes()` to distinguish between custom and fallback MIME types in property variants like ImageProperty and AudioProperty
- Method `assertValidUploadPath()` to ensure upload path exists (or creates it) and checks if writable
- Methods `isAcceptedMimeType()` and `isAcceptedFilesize()`
- Methods `generateExtensionFromFile()`, `generateExtensionFromMimeType()`, and `resolveExtensionFromMimeType()`
- Method `formatFilesize()` to format bytes into a human-readable unit
- Method `pathFor()` to make an absolute path to a directory or file
- Method `parseValAsFileList()` to flatten value object to simplify validation and parsing of values

Removed:
- Aliases `filesize()`, `mimetype()`, `mimetypeFor()` in favour of their get-prefixed methods

Changed:
- Bump branch-alias to 0.11
- Moved default MIME types from `getAcceptedMimeTypes()` to new `getDefaultAcceptedMimetypes()` for ImageProperty and AudioProperty
- Fallback in method `getMimetype()` to retrieve the MIME type of the first value
- Fallback in method `getFilesize()` to retrieve the MIME type of the first value
- Renamed validation methods and internal routines to validate MIME type and size of available values (ignoring `getMimetype()` and `getFilesize`)
- Unified methods `dataUpload()` and `fileUpload()` to throw exceptions
- Unified methods `saveDataUploads()` and `saveDataUploads()` to catch exceptions and log errors
- Replaced validation methods with new `isAccepted*()` methods inside `dataUpload()` and `fileUpload()`
- Method `dataUpload()` to generate filename and extension before calling `uploadTarget()`
- Method `uploadTarget()` to simplify making of filename
- Method `generateFilename()` to use "fallbackFilename" and sanitize value

Fixed:
- Edge case where MIME type resolution returns "inode/x-empty" or empty string
- Edge cases where a string is expected

composer.json

@@ -19,14 +19,14 @@
     "prefer-stable": true,
     "extra": {
         "branch-alias": {
-            "dev-master": "0.10.x-dev"
+            "dev-master": "0.11.x-dev"
         }
     },
     "require": {
         "php": ">=5.6.0 || >=7.0",
         "ext-fileinfo": "*",
-        "ext-PDO": "*",
-        "ext-SimpleXML": "*",
+        "ext-pdo": "*",
+        "ext-simplexml": "*",
         "psr/log": "^1.0",
         "psr/cache": "^1.0",
         "locomotivemtl/charcoal-config": "~0.9",

src/Charcoal/Property/AudioProperty.php

@@ -85,51 +85,52 @@ public function getMaxLength()
     }
 
     /**
+     * Retrieves the default list of acceptable MIME types for uploaded files.
+     *
+     * This method should be overriden.
+     *
      * @return string[]
      */
-    public function getAcceptedMimetypes()
+    public function getDefaultAcceptedMimetypes()
     {
         return [
             'audio/mp3',
             'audio/mpeg',
             'audio/ogg',
+            'audio/webm',
             'audio/wav',
+            'audio/wave',
             'audio/x-wav',
+            'audio/x-pn-wav',
         ];
     }
 
     /**
-     * Generate the file extension from the property's value.
+     * Resolve the file extension from the given MIME type.
      *
-     * @param  string $file The file to parse.
-     * @return string The extension based on the MIME type.
+     * @param  string $type The MIME type to resolve.
+     * @return string|null The extension based on the MIME type.
      */
-    public function generateExtension($file = null)
+    protected function resolveExtensionFromMimeType($type)
     {
-        if (is_string($file)) {
-            if (in_array($file, $this->getAcceptedMimetypes())) {
-                $mime = $file;
-            } else {
-                $mime = $this->getMimetypeFor($file);
-            }
-        } else {
-            $mime = $this->getMimetype();
-        }
-
-        switch ($mime) {
+        switch ($type) {
             case 'audio/mp3':
             case 'audio/mpeg':
                 return 'mp3';
 
             case 'audio/ogg':
                 return 'ogg';
 
+            case 'audio/webm':
+                return 'webm';
+
             case 'audio/wav':
+            case 'audio/wave':
             case 'audio/x-wav':
+            case 'audio/x-pn-wav':
                 return 'wav';
-
-            default:
-                return '';
         }
+
+        return null;
     }
 }