Merge pull request #7204 from kenjis/docs-uploaded_files.rst

docs: improve uploaded_files.rst

Author: kenjis

user_guide_src/source/libraries/uploaded_files.rst

@@ -307,20 +307,46 @@ version, use ``getMimeType()`` instead:
 Moving Files
 ============
 
+with Original Filename
+----------------------
+
 Each file can be moved to its new location with the aptly named ``move()`` method. This takes the directory to move
 the file to as the first parameter:
 
 .. literalinclude:: uploaded_files/016.php
 
-By default, the original filename was used. You can specify a new filename by passing it as the second parameter:
+By default, the original filename was used.
+
+with New Filename
+-----------------
+
+You can specify a new filename by passing it as the second parameter:
 
 .. literalinclude:: uploaded_files/017.php
 
+Overwriting Existing File
+-------------------------
+
+By default, if the destination file already exists, a new filename will be used.
+For example, if **image_name.jpg** already exists in the directory, then the
+filename will be **image_name_1.jpg** automatically.
+
+You can overwrite the existing file by passing ``true``
+as the third parameter:
+
+.. literalinclude:: uploaded_files/022.php
+
+Check if the File Moved
+-----------------------
+
 Once the file has been removed the temporary file is deleted. You can check if a file has been moved already with
 the ``hasMoved()`` method, which returns a boolean:
 
 .. literalinclude:: uploaded_files/018.php
 
+When Moving Fails
+-----------------
+
 Moving an uploaded file can fail, with an HTTPException, under several circumstances:
 
 - the file has already been moved

user_guide_src/source/libraries/uploaded_files/022.php

@@ -0,0 +1,3 @@
+<?php
+
+$file->move(WRITEPATH . 'uploads', null, true);