Improve documentation

See #2825

diff --git a/wcfsetup/install/files/lib/action/AJAXFileUploadAction.class.php b/wcfsetup/install/files/lib/action/AJAXFileUploadAction.class.php
index 4b2bdc9e7fd8e44b8508a1905501e54140163a33..b8dfbfd9189827d161658e8005cd73cf1b5d7405 100644 (file)
--- a/wcfsetup/install/files/lib/action/AJAXFileUploadAction.class.php
+++ b/wcfsetup/install/files/lib/action/AJAXFileUploadAction.class.php
@@ -89,7 +89,7 @@ class AJAXFileUploadAction extends AbstractSecureAction {
                foreach ($_FILES['__files']['tmp_name'] as $id => $tmpName) {
                        if ($field->isImageOnly()) {
                                if (@getimagesize($tmpName) === false) {
-                                       if (!$field->svgImagesAllowed() || !in_array(FileUtil::getMimeType($tmpName), [
+                                       if (!$field->svgImageAllowed() || !in_array(FileUtil::getMimeType($tmpName), [
                                                        'image/svg',
                                                        'image/svg+xml'
                                                ])) {
@@ -102,7 +102,7 @@ class AJAXFileUploadAction extends AbstractSecureAction {
                                }
                                
                                $allowedExtensions = ['jpeg', 'jpg', 'png', 'gif'];
-                               if ($field->svgImagesAllowed()) $allowedExtensions[] = 'svg';
+                               if ($field->svgImageAllowed()) $allowedExtensions[] = 'svg';
                                
                                if (!in_array(pathinfo($_FILES['__files']['name'][$id], PATHINFO_EXTENSION), $allowedExtensions)) {
                                        $response['error'][$i++] = [
@@ -123,7 +123,7 @@ class AJAXFileUploadAction extends AbstractSecureAction {
                                continue;
                        }
                        
-                       $uploadFile = new UploadFile($tmpFile, $_FILES['__files']['name'][$id], true, false, $field->svgImagesAllowed());
+                       $uploadFile = new UploadFile($tmpFile, $_FILES['__files']['name'][$id], true, false, $field->svgImageAllowed());
                        
                        UploadHandler::getInstance()->addFileByInternalId($this->internalId, $uploadFile);
                        

diff --git a/wcfsetup/install/files/lib/system/file/upload/UploadField.class.php b/wcfsetup/install/files/lib/system/file/upload/UploadField.class.php
index 096b4ae479d661883c18c6fb2e4bde1309792d3d..e5d98d2a2e1615b0d5e5250dcc1dde130f007684 100644 (file)
--- a/wcfsetup/install/files/lib/system/file/upload/UploadField.class.php
+++ b/wcfsetup/install/files/lib/system/file/upload/UploadField.class.php
@@ -30,20 +30,18 @@ class UploadField {
        public $internalId = null;
        
        /**
-        * Indicates whether the field is image only.
+        * This flag indicates whether only images can uploaded via this field.
         * @var boolean
         */
        public $imageOnly = false;
        
        /**
-        * Indicates whether the field supports svg images.
-        * 
-        * <strong>Heads up:</strong> svg images can contain code, therefore do not
+        * This flag indicates whether only images can uploaded via this field.
+        * <strong>Heads up:</strong> SVG images can contain bad code, therefore do not
         * use this option, outside the acp or check the file whether remote code is contained.
-        * 
         * @var boolean
         */
-       public $allowSvgImages = false;
+       public $allowSvgImage = false;
        
        /**
         * UploadField constructor.
@@ -73,7 +71,7 @@ class UploadField {
        }
        
        /**
-        * Returns true, if the upload is image only.
+        * Returns `true` if only images can be uploaded via this field and returns `false` otherwise.
         * 
         * @return boolean
         */
@@ -82,12 +80,12 @@ class UploadField {
        }
        
        /**
-        * Returns true, if svg images are allowed.
+        * Returns true, if the field can contain svg images in the image only mode.
         * 
         * @return boolean
         */
-       public function svgImagesAllowed() {
-               return $this->allowSvgImages;
+       public function svgImageAllowed() {
+               return $this->allowSvgImage;
        }
        
        /**
@@ -118,7 +116,8 @@ class UploadField {
        }
        
        /**
-        * Set the image only flag. 
+        * Sets the flag for `imageOnly`. This flag indicates whether only images
+        * can uploaded via this field. Other file types will be rejected during upload.
         * 
         * @param       boolean       $imageOnly
         */
@@ -127,11 +126,23 @@ class UploadField {
        }
        
        /**
-        * Set the image only flag. 
+        * Sets the flag for `allowSvgImage`. This flag indicates whether
+        * SVG images should be handled as image, if the upload field is
+        * image only (if this field is not image only, this method will
+        * throw an exception).
+        * 
+        * <strong>Heads up:</strong> SVG images can contain bad code, therefore do not
+        * use this option, outside the acp or check the file whether remote code is contained.
+        * 
+        * @param       boolean       $allowSvgImage
         * 
-        * @param       boolean       $allowSvgImages
+        * @throws      \BadMethodCallException         if the imageOnly flag isn't set to true
         */
-       public function setAllowSvgImages($allowSvgImages) {
-               $this->allowSvgImages = $allowSvgImages;
+       public function setAllowSvgImage($allowSvgImage) {
+               if (!$this->isImageOnly()) {
+                       throw new \BadMethodCallException('Allowing SVG images is only relevant, if the `imageOnly` flag is set to `true`.');
+               }
+               
+               $this->allowSvgImage = $allowSvgImage;
        }
 }

diff --git a/wcfsetup/install/files/lib/system/form/builder/field/UploadFormField.class.php b/wcfsetup/install/files/lib/system/form/builder/field/UploadFormField.class.php
index 4f30df8b93765f4ac0c5a52d5c96a905a26f8230..ce5ae762a7fe1eb1a71658896f5d569881d2b4fc 100644 (file)
--- a/wcfsetup/install/files/lib/system/form/builder/field/UploadFormField.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/field/UploadFormField.class.php
@@ -23,13 +23,15 @@ class UploadFormField extends AbstractFormField {
        use TMinimumFormField;
        
        /**
-        * imageOnly flag for the upload field.
+        * This flag indicates whether only images can uploaded via this field.
+        * <strong>Heads up:</strong> SVG images can contain bad code, therefore do not
+        * use this option, outside the acp or check the file whether remote code is contained.
         * @var boolean
         */
        protected $imageOnly = false;
        
        /**
-        * allowSvgImage flag.
+        * This flag indicates whether SVG images are treated as image in the image only mode.
         * @var boolean
         */
        protected $allowSvgImage = false;
@@ -66,7 +68,7 @@ class UploadFormField extends AbstractFormField {
                $uploadField = new UploadField($this->getId());
                $uploadField->maxFiles = $this->getMaximum();
                $uploadField->setImageOnly($this->isImageOnly());
-               $uploadField->setAllowSvgImages($this->svgImageAllowed());
+               $uploadField->setAllowSvgImage($this->svgImageAllowed());
                
                return $uploadField;
        }
@@ -226,7 +228,8 @@ class UploadFormField extends AbstractFormField {
        }
        
        /**
-        * Sets the imageOnly flag for this field.
+        * Sets the flag for `imageOnly`. This flag indicates whether only images 
+        * can uploaded via this field. Other file types will be rejected during upload.
         *
         * @param       boolean         $imageOnly
         * @return      static                          this field
@@ -238,7 +241,13 @@ class UploadFormField extends AbstractFormField {
        }
        
        /**
-        * Sets the imageOnly flag for this field.
+        * Sets the flag for `allowSvgImage`. This flag indicates whether 
+        * SVG images should be handled as image, if the upload field is 
+        * image only (if this field is not image only, this method will 
+        * throw an exception). 
+        * 
+        * <strong>Heads up:</strong> SVG images can contain bad code, therefore do not
+        * use this option, outside the acp or check the file whether remote code is contained.
         *
         * @param       boolean         $allowSvgImages
         * @return      static                          this field
@@ -265,7 +274,7 @@ class UploadFormField extends AbstractFormField {
        }
        
        /**
-        * Returns true, if the field can contain svg images.
+        * Returns true, if the field can contain svg images in the image only mode.
         *
         * @return      boolean
         */