You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • UAPI Functions - Fileman::upload_files
Skip to end of metadata
Go to start of metadata

Description

This function uploads files.

Note:

For more information about how to use this function in your custom code, read our Use UAPI's Fileman::upload_files Function in Custom Code tutorial.

Important:

In cPanel & WHM version 76 and later, when you disable the File Storage role, the system disables this function.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Fileman/upload_files?dir=/home/user/public_html&file-1=example.html&file-2=rankand.html&getdiskinfo=0&overwrite=0&permissions=0777



Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Upload files to public_html directory.
$upload_files = $cpanel->uapi(
    'Fileman', 'upload_files',
		array(
		'dir'			    => '/home/user/public_html',
		'file-1'			=> 'nail.html',
		'file-2'			=> 'rankand.html',
		'getdiskinfo'		=> '0',
		'overwrite'		    => '0',
		'permissions'		=> '0777',
		 )
);


Note:

For more information, read our Guide to the LiveAPI System.


 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Upload files to public_html directory.
my $ upload_files = $cpliveapi->uapi(
 	'Fileman', 'upload_files',
		{
		'dir'			    => 'public_html',
		'file-1'			=> 'nail.html',
		'file-2'			=> 'rankand.html',	
	    'getdiskinfo'		=> '0',
		'overwrite'		    => '0',
		'permissions'		=> '0777',
		 }
 );


Note:

For more information, read our Guide to the LiveAPI System.


 Command Line
uapi --user=username Fileman upload_files dir=%2Fhome%2Fusername%2Fpublic_html file-1=example.html file-2=rankand.html getdiskinfo=0 overwrite=0 permissions=0777


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
	"messages": null,
	"errors": null,
	"status": 1,
	"metadata": {

	},
	"data": {
		"diskinfo": {
			"file_upload_max_bytes": 100,
			"file_upload_must_leave_bytes": 100,
			"file_upload_remain": 100,
			"filesremain": 100,
			"fileslimit": 100,
			"filesused": 100,
			"spaceremain": 100,
			"spacelimit": 100,
			"spaceused": 100
		},
		"uploads": [{
			"file": "example.html",
			"size": 100,
			"status": 1,
			"reason": null,
			"warnings": null
		}, {
			"file": "test.html",
			"size": 100,
			"status": 1,
			"reason": null,
			"warnings": null
		}]

	}
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParametersTypeDescriptionPossible valuesExample
dirstring

Required

The directory to which to upload the files.

A valid directory on the server, relative to the user's home directory.public_html
file-*string

Required

The files to upload.

Important:

  • You must pass this parameter for each file to upload.
  • You must increment each variable. For example, pass the first file as file-1 and the second file as file-2.
A valid filename on the server.nail.html
getdiskinfoBoolean

Whether to display the disk information after the upload finish.

This parameter defaults to 0.

  • 1 — Display the disk information.
  • 0 — Do not display the disk information.
0
overwriteBoolean

Whether to overwrite any files with identical names.

This parameter defaults to 0.

  • 1 — Overwrite files.
  • 0 — Do not overwrite files.
0
permissionsstring

The file's numerical permissions.

This parameter defaults to 0644.

An integer value, in octal notation.0755

Returns

ReturnTypeDescriptionPossible valuesExample
diskinfohashInformation about the upload directory.This hash contains the file_upload_max_bytes, file_upload_must_leave_bytes, file_upload_remain, filesremain, fileslimit, filesused, spaceremain, spacelimit, and spaceused returns.

file_upload_max_bytes

integer

The maximum file size that you can upload through the File Manager.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

file_upload_must_leave_bytes

integer

The amount of disk space that must be available to avoid quota issues due to file uploads.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

file_upload_remain

integer

The file upload space that still remains on the account.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

filesremain

integer

The disk space that remains on the account.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

fileslimit

integer

The account's disk space quota that is reserved for files.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

filesused

integer

The disk space that the files on the account use.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

spaceremain

integer

The disk space that still remains on the account.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

spacelimit

integer

The account's disk space quota.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100

spaceused

integer

The amount of disk space used.

The function returns this value in the diskinfo hash.

  • A positive integer, in kilobytes (KB), megabytes (MB), or gigabytes (GB).
  • ∞  — The account has unlimited disk space.
100
uploadsarray of hashes

Information about the files that the function uploads to the directory.

Each hash contains the file, size, status, and reason returns and the warnings array.

file

stringThe original name of the uploaded file.A valid file name.example.html

size

integerThe size of the file, in bytes.A valid positive integer.100

status

BooleanWhether the upload succeeded and the system copied the file to the directory.
  • 1 — The file uploaded successfully.
  • 0 — The file failed to upload.
1

reason

string

If the upload failed, this return contains the reason for the failure.A valid string.null

warnings

arrayIf the upload failed, this return contains any file warnings from the system.A valid string.null