clarified how/when to use client or guessed mime-types and extensions on a File instance (closes #5039)

src/Symfony/Component/HttpFoundation/File/File.php

@@ -49,9 +49,15 @@ class File extends \SplFileInfo
      *
      * If the mime type is unknown, returns null.
      *
+     * This method uses the mime type as guessed by getMimeType()
+     * to guess the file extension.
+     *
      * @return string|null The guessed extension or null if it cannot be guessed
      *
      * @api
+     *
+     * @see ExtensionGuesser
+     * @see getMimeType()
      */
     public function guessExtension()
     {
@@ -64,12 +70,14 @@ class File extends \SplFileInfo
     /**
      * Returns the mime type of the file.
      *
-     * The mime type is guessed using the functions finfo(), mime_content_type()
-     * and the system binary "file" (in this order), depending on which of those
-     * is available on the current operating system.
+     * The mime type is guessed using a MimeTypeGuesser instance, which uses finfo(),
+     * mime_content_type() and the system binary "file" (in this order), depending on
+     * which of those are available.
      *
      * @return string|null The guessed mime type (i.e. "application/pdf")
      *
+     * @see MimeTypeGuesser
+     *
      * @api
      */
     public function getMimeType()

src/Symfony/Component/HttpFoundation/File/UploadedFile.php

@@ -134,11 +134,16 @@ class UploadedFile extends File
     /**
      * Returns the file mime type.
      *
-     * It is extracted from the request from which the file has been uploaded.
-     * Then is should not be considered as a safe value.
+     * The client mime type is extracted from the request from which the file
+     * was uploaded, so it should not be considered as a safe value.
+     *
+     * For a trusted mime type, use getMimeType() instead (which guesses the mime
+     * type based on the file content).
      *
      * @return string|null The mime type
      *
+     * @see getMimeType
+     *
      * @api
      */
     public function getClientMimeType()
@@ -146,6 +151,31 @@ class UploadedFile extends File
         return $this->mimeType;
     }
 
+    /**
+     * Returns the extension based on the client mime type.
+     *
+     * If the mime type is unknown, returns null.
+     *
+     * This method uses the mime type as guessed by getClientMimeType()
+     * to guess the file extension. As such, the extension returned
+     * by this method cannot be trusted.
+     *
+     * For a trusted extension, use guessExtension() instead (which guesses
+     * the extension based on the guessed mime type for the file).
+     *
+     * @return string|null The guessed extension or null if it cannot be guessed
+     *
+     * @see guessExtension()
+     * @see getClientMimeType()
+     */
+    public function guessClientExtension()
+    {
+        $type = $this->getMimeType();
+        $guesser = ExtensionGuesser::getInstance();
+
+        return $guesser->guess($type);
+    }
+
     /**
      * Returns the file size.
      *