WordPress.org

Plugin Directory

WordPress File Upload

Simple yet very powerful plugin to allow users to upload files to your website from any page and manage the uploaded files

Attributes

The easiest way to use the plugin is to put the shortcode [wordpress_file_upload] in the page. In this case, the plugin will use the default functionality.

If you want to customize the plugin (define the upload path, use file filter, change title and button text etc.) then you can use attributes. Go to Dashboard / Settings / WordPress File Upload and then press Shortcode Composer. By selecting the attributes of your choice, the shortcode will be automatically generated. Then you can copy and paste it in any page.

A detailed list of attributes, together with instructions is shown below:

General Options

Basic Functionalities

  • uploadid: This is the ID of every instance of the plugin inside the same page. Valid values are 1,2,3... Please use a different value for every instance.
  • singlebutton: If this attribute is set to "true", only Upload Button will be shown and file will be automatically uploaded when selected. Default value is "false".
  • uploadpath: This is the path of the upload directory. The path must be relative to wp-content folder of your WordPress website. For instance, if your upload directory is "wp-content/uploads/myuploaddir", then uploadpath must have the value "uploads/myuploaddir". The default value is "uploads", meaning that the files will be uploaded to wp-content/uploads dir. If you put the variable "%username%" inside the uploadpath string, then this variable will be replaced by the username of the user currently logged in. If you want to upload files outside wp-content folder, then put a double dot (..) at the beginning of your uploadpath value.

Filters

  • uploadrole: This is the roles that are allowed to upload files. Default role is "all". If you use other roles, like "editor", then only users of this role and also of role "administrator" will be able to upload files. You can set multiple roles, separated by comma, e.g. "editor, author". If you set uploadrole to "all" then all users, even guests, will be able to upload files.
  • uploadpatterns: This is the filter of the uploaded files. Default value is ".", meaning that all files can be uploaded. Use this attribute to restrict the types of files that can be uploaded. For instance, in order to upload only pdf files put "*.pdf". You can use more that one filters, separated by comma, for instance "*.pdf,*.doc".
  • maxsize: This is the maximum size in MBytes of the uploaded files. Use this attribute to restrict the upload of files larger that this value. Default value is "10", meaning that you cannot upload files larger than 10MBytes.

Upload Path and Files

  • createpath: If this attribute is set to "true", the upload directory, defined by uploadpath, will be created in case it does not exist. Default value is "false".
  • forcefilename: The plugin by default will modify the filename if it contains invalid or non-english characters. By setting this attribute to "true" the plugin will not change the filename. Default value is "false".
  • accessmethod: This attributes defines the method to create directories and upload files. Default value is "normal". If it is set to "ftp", then the plugin will attempt to create directories and upload files using ftp access. In order to do this, the attribute ftpinfo must also be filled with valid ftp access information. Use this attribute when you cannot upload files, access uploaded files or cannot copy or delete uploaded files because of SAFE MODE restrictions, or because the owner of the file is the domain administrator.
  • ftpinfo: This attribute defines the ftp access information. It has the syntax username:password@domain. If username, password or domain contains the characters (:) or (@), then replace them with (\:) and (\@) in order to avoid misreading of the attribute.
  • useftpdomain: This attribute is used when the ftp domain used to upload files is in different domain than WordPress installation. If it is set to "true" (and also uploadmethod is "ftp"), then the domain that will be used to upload files will be the one defined in ftpinfo attribute. Default value is "false".
  • ftppassivemode: If this attribute is set to "true", FTP passive mode will be used instead of active mode. It is used if files fail to upload when using FTP method. Default value is "false".
  • ftpfilepermissions: Force the uploaded files to have specific permissions. This is a 4-digit octal number, e.g. 0777. If left empty, then the ftp server will define the permissions. Default value is "".
  • showtargetfolder: This attribute defines if a message with the upload directory will be shown. Default value is "false".
  • askforsubfolders: This attribute defines if the user can select a subfolder to upload the file. Default value is "false". If set to "true", then the user is able to select a subfolder of the path, defined by the attribute uploadpath, to upload a file through a drop down list. This attributed is used together with attribute subfoldertree, which defines the subfolders.
  • subfoldertree: This attribute defines the structure of the subfolders that the user can select to upload a file. Default value is "". The format of this attribute is as follows: the subfolders are separated by commas (,), e.g. "subfolder1, subfolder2". It is possible to use nested subfolders (a folder inside another folder). To do this place stars (*) before the name of the subfolder. The number of stars determines nesting level, e.g. "subfolder1, *nested1, *nested2, **nested3". Please note that the first subfolder must be the name of the folder defined by attribute uploadpath (only the last part) without any stars, while all the next subfolders must have at least one star. The user has also the capability to use a different name (from the actual subfolder name) to be shown in the drop down list for every subfolder, by separating the actual and shown name using the slash (/) symbol, e.g. "subfolder1, *subfolder2/shownname2, *subfolder3/shownname3". For defining a default value that will be preselected use the (&) symbol before the item name (but after the stars, e.g. **&nested3.
  • dublicatespolicy: This attribute defines what to do when the upload file has the same name with another file inside target directory. If it is set to "overwrite" then the upload file will replace the existing file. If it is set to "reject" then the upload operation will be cancelled. If it is set to "maintain both" then the upload file will be saved inside the target directory with another name, in order to keep both files. Default value is "overwrite".
  • uniquepattern: This attribute defines how to save the upload file when a file with the same name already exists inside the target directory. If it is set to "index" then the upload file will be saved with a numeric suffix, like (1), (2) etc. in order to keep the name of the uploaded file unique. If it is set to "datetimestamp", then the suffix will be an encoded datetime of the upload operation. The plugin ensures that the name of the uploaded file will be unique, in order to avoid accidental replacement of existing files. Default value is "index".

Redirection

  • redirect: This attribute defines if the user will be redirected to another web page when the file is uploaded successfully. Default value is "false".
  • redirectlink: This attribute defines the url of the redirection page. Please use the prefix "http://" if the redirection page is in another domain, otherwise the server will assume that the url is relative to the server path.

Other Administrator Options

  • adminmessages: This attribute offers the option to administrator users to receive additional information about upload errors. These messages will be visible only to administrators. Default value is "false".
  • forceclassic: This attribute defines if the plugin will use the old classic functionality to upload files (using forms) or ajax functionality (supported in HTML5). Default value is "false". Please note that if your browser does not support HTML ajax functionality, then the plugin will automatically switch to classic one.
  • testmode: This attribute defines if the plugin will be shown in test mode. Default value is "false". If it is set to "true", then the plugin will obtain a "dummy" functionality (it will not be able to upload files) and it will appear showing all of its objects (the selection of subfolders, progress bar, a test message), while the buttons will show a "Test Mode" message when pressed. This option can be used to configure the dimensions of the individual objects of the plugin more easily.
  • debugmode: This attribute defines if the plugin will show debug information. Default value is "false". If it is set to "true", then the plugin will show in the message box any warnings and errors generated by PHP during the upload process. It can be used by administrators for deep debugging. For generation of PHP warnings and errors, global WordPress WP_DEBUG constant must be enabled.

Placements

Plugin Component Positions

  • placements: This attribute can be used to change the placement of the objects of the plugin. Default value is "title/filename+selectbutton+uploadbutton/subfolders/userdata/progressbar/message". Every line is separated by a slash (/). To put more than one objects to the same line, separate them with a plus (+). The name of every object is shown below.

Labels

Title

  • uploadtitle: The title of the plugin. Default value is "Upload a file".

Buttons

  • selectbutton: The title of the select button. Default value is "Select File".
  • uploadbutton: The title of the upload button. Default value is "Upload File".

Upload Folder

  • targetfolderlabel: This attribute defines the text for the message for the upload directory. Default value is "Upload Directory".

Upload Messages

  • successmessage: This attribute defines the message to be shown upon successful upload. Default value is "File %filename% uploaded successfully". You can use the variables %filename% and %filepath% inside the message, as explained below.
  • warningmessage: This attribute defines the message to be shown upon successful upload but with warnings. Default value is "File %filename% uploaded successfully but with warnings". You can use the variables %filename% and %filepath% inside the message, as explained below.
  • errormessage: This attribute defines the message to be shown upon upload failure. Default value is "File %filename% not uploaded". You can use the variables %filename% and %filepath% inside the message, as explained below.
  • waitmessage: This attribute defines the message to be shown while uploading. Default value is "File %filename% is being uploaded". You can use the variables %filename% and %filepath% inside the message, as explained below.

Notifications

Email Notifications

  • notify: If this attribute is set to "true", then an email will be sent to the addresses defined by the attribute notifyrecipients to inform them that a new file has been uploaded.
  • notifyrecipients: This attribute defines the list of email addresses to receive the notification message that a new file has been uploaded. More that one address can be defined, separated by comma (,). You can use variables inside this attribute, as explained below.
  • notifyheaders: This attribute defines additional headers to be included in the notification email (e.g. set "From", "Cc" and "Bcc" parameters or use HTML code instead of text). Default value is "". For example, in order to send HTML email please set this attribute to "Content-type: text/html".
  • notifysubject: This attribute defines the subject for the notification message. Default value is "File Upload Notification". You can use variables inside this attribute, as explained below.
  • notifymessage: This attribute defines the body text for the notification message. Default value is "Dear Recipient, this is an automatic delivery message to notify you that a new file has been uploaded. Best Regards". You can use variables inside this attribute, as explained below.
  • attachfile: This attribute defines if the uploaded file will be attached to the notification email. Default value is "false".

Colors

Upload Message Colors

  • successmessagecolor: This attribute defines the color of the message shown upon successful upload. Default value is "green". This attribute is no longer used but is maintained for backward compatibility. Please use successmessagecolors instead.
  • successmessagecolors: This attribute defines the colors of the message shown upon successful upload. Default value is "#006600,#EEFFEE,#006666". The first value is the text color, the second the background color and the third the border color.
  • warningmessagecolors: This attribute defines the colors of the message shown upon successful upload but with warnings. Default value is "#F88017,#FEF2E7,#633309". The first value is the text color, the second the background color and the third the border color.
  • failmessagecolors: This attribute defines the colors of the message shown upon upload failure. Default value is "#660000,#FFEEEE,#666600". The first value is the text color, the second the background color and the third the border color.
  • waitmessagecolors: This attribute defines the colors of the message shown while file uploading. Default value is "#666666,#EEEEEE,#333333". The first value is the text color, the second the background color and the third the border color.

Dimensions

Plugin Component Widths

  • widths: This attribute can be used to define the width of every individual object of the plugin. Default value is "". To define the width of an individual object, simply put the name of the object and the width, separated by the (:) character (e.g. "title:100px"). To define more than one objects separate them with comma (,).

Plugin Component Heights

  • heights: This attribute can be used to define the height of every individual object of the plugin. Default value is "". To define the height of an individual object, simply put the name of the object and the height, separated by the (:) character (e.g. "title:20px"). To define more than one objects separate them with comma (,).

Additional Fields

Additional Data Fields

  • userdata: This attribute defines if additional text information will be requested by the user. If set to "true", then an additional textbox will appear, prompting the user to put text data. These data will be sent to email recipients, if email notification has been activated and %userdata% variable exists inside notifymessage attribute. Default value is "false".
  • userdatalabel: This attribute defines the labels of the userdata fields. Separate each field with slash "/". If you want a field to be required, then preceed an asterisk () before the label. Example to create 2 fields, an optional Name and a required Email field: userdatalabel="Name/Email (required)". Default value is "Your message".

Interoperability

Connection With Other Plugins

  • filebaselink: This attribute defines if this plugin will be linked to wp-filebase plugin. Wp-filebase is another plugin with which you can upload files and then show them in your pages in a customizable way. If you set this attribute to "true", then you can upload files inside wp-filebase directories using wordpress_file_upload and then update the databases of wp-filebase, so that it is informed about the new uploads. The default value is "false". Please note that this attribute does not check to see if wp-filebase is installed and active, so be sure to have wp-filebase active if you want to use it.

Connection With Other WordPress Features

  • medialink: This attribute defines that uploaded files will be added to Media of the WordPress website when set to "true". Default value is "false". Credits for this functionality to Aaron Olin.
  • postlink: This attribute defines that uploaded files will be added to the current page (or post) as attachments when set to "true". Default value is "false".

You can use any of these attributes to customize the plugin. The way to use these attributes is the following:

[wordpress_file_upload attribute1=value1 attribute2=value2]

Here are some examples:

[wordpress_file_upload uploadtitle="Upload files to the Upload dir"]
[wordpress_file_upload uploadtitle="Upload files to the Upload dir" uploadpath="uploads/myuploaddir"]
[wordpress_file_upload uploadid="1" uploadpath="../myuploaddir"]
[wordpress_file_upload uploadpath="uploads/users/%username%" createpath="true"]
[wordpress_file_upload uploadpath="uploads/myuploaddir" notify="true" notifyrecipients="name1@address1.com, name2@address2.com"]
[wordpress_file_upload uploadpath="/uploads/myuploaddir" askforsubfolders="true" subfoldertree="myuploaddir/My Upload Directory,*subfolder1/Subfolder1 Inside myuploaddir,**inner/2nd Level Nested Dir, *reports/Reports"]
[wordpress_file_upload uploadrole="all" uploadpath="/uploads/filebase/%username%" createpath="false" notify="true" notifyrecipients="myname@domain.com" notifysubject="A new file has been uploaded!" attachfile="true" askforsubfolders="true" subfoldertree="admin/Administrator,*root/Root Folder,**inner, *reports/Reports" filebaselink="true" widths="filename:150px, selectbutton:80px, uploadbutton:80px, progressbar:220px, message:368px, subfolders_label:100px, subfolders_select:125px" placements="title/filename+subfolders/selectbutton+uploadbutton+progressbar/message"]
[wordpress_file_upload uploadpath="uploads/myuploaddir" notify="true" notifyrecipients="name1@address1.com, name2@address2.com" notifymessage="File %filename% has been received, together with fields Name:%userdata0%, Email:%userdata1%" userdata="true" userdatalabel="Name/*Email (required)"]
[wordpress_file_upload uploadpath="uploads/myuploaddir" notify="true" notifyrecipients="name1@address1.com, name2@address2.com" notifymessage="This is a test HTML message body.<br/><br/>This word is <em>italic</em> and this is <strong>bold</strong>." notifyheaders="Content-type: text/html"]

Variables

From version 1.2 variables are supported inside attributes.

A variable is a string surrounded by percent characters, in the form %variable_name%. This variable is dynamically replaced by another string whenever the plugin is executed.

For instance, if the variable %username% is used inside uploadpath attribute, then it will be replaced by the username of the user who is currently logged in every time a file is uploaded. By this way, every user can upload files to a separate folder, without any additional programming.

For the time being, the following variables are supported:

  • %userid%: Is replaced by the id of the current user. Can be used inside attribute uploadpath.
  • %username%: Is replaced by the username of the current user. Can be used inside attributes uploadpath, notifysubject and notifymessage.
  • %useremail%: Is replaced by the email of the current user. Can be used inside attributes notifyrecipients, notifysubject, notifymessage and redirectlink.
  • %filename%: Is replaced by the filename (not including path information) of the uploaded file. Can be used inside attributes notifysubject, notifymessage, successmessage and redirectlink.
  • %filepath%: Is replaced by the filepath (full path and filename) of the uploaded file. Can be used inside attributes notifysubject, notifymessage and successmessage.
  • %blogid%: Is replaced by the blog_id of the current site. Can be used inside attribute uploadpath, notifysubject and notifymessage.
  • %userdataXXX%: Is replaced by the additional message that the user has sent together with the file upload. XXX is the number of the field (starting from 0). The shortcode attribute userdata must have been set to "true". Can be used inside attributes uploadpath, notifysubject, notifymessage and notifyrecipients.
  • %pagetitle%: Is replaced by the title of the current page. Can be used inside attribute uploadpath, notifysubject and notifymessage.
  • %pageid%: Is replaced by the id of the current page. Can be used inside attribute uploadpath, notifysubject and notifymessage.

In addition, some special variables, which are used to replace literals not allowed in shortcodes (such as double quotes or brackets), are also supported. They can be used in attributes that receive free text (like button labels, email notification body etc.). These special variables are:

  • %n%: When used inside an attribute (e.g. inside notifymessage) it will be replaced by a change-of-line character (\n).
  • %dq%: When used inside an attribute it will be replaced by a double quote (").
  • %brl%: When used inside an attribute it will be replaced by an opening bracket ([).
  • %brr%: When used inside an attribute it will be replaced by a closing bracket (]).

Filters / Actions

From version 2.4.1 filters and actions are supported in order to allow programmers to integrate WordPress File Upload plugin with other plugins.

The following filters are supported:

wfu_before_file_check

It is executed before file is uploaded and before any internal file checks, in order to allow the filter to perform its own checks or change some basic upload parameters, such as filename or userdata. You can use it as follows:

add_filter('wfu_before_file_check', 'wfu_before_file_check_handler', 10, 2);

//The following function takes two parameters, $changable_data and $additional_data.
//  $changable_data is an array that can be modified by the filter and contains the items:
//    file_path: the full path of the uploaded file
//    user_data: an array of user data values, if userdata are activated
//    error_message: initially it is set to an empty value, if the handler sets a non-empty value then upload of the file will be cancelled showing this error message (message will be shown only to administrators if adminmessages attribute has been activated)
//  $additional_data is an array with additional data to be used by the filter (but cannot be modified) as follows:
//    shortcode_id: this is the id of the plugin, as set using uploadid attribute; it can be used to apply this filter only to a specific instance of the plugin (if it is used in more than one pages or posts)
//    file_unique_id: this id is unique for each individual file upload and can be used to identify each separate upload
//    file_size: the size of the uploaded file
//    user_id: the id of the user that submitted the file for upload
//    page_id: the id of the page from where the upload was performed (because there may be upload plugins in more than one page)
//The function must return the final $changable_data.
function wfu_before_file_check_handler($changable_data, $additional_data) {
    // Add code here...
    return $changable_data;
}

wfu_before_file_upload

It is executed right before file is uploaded, in order to allow the filter to change the file name. You can use it as follows:

add_filter('wfu_before_file_upload', 'wfu_before_file_upload_handler', 10, 2);

//The following function takes two parameters, $file_path and $file_unique_id.
//  $file_path is the filename of the uploaded file (after all internal checks have been applied) and can be modified by the filter.
//  $file_unique_id is is unique for each individual file upload and can be used to identify each separate upload.
//The function must return the final $file_path.
//If additional data are required (such as user id or userdata) you can get them by implementing the previous filter
//wfu_before_file_check and link both filters by $file_unique_id parameter.
//Please note that no filename validity checks will be performed after the filter. The filter must ensure that filename is valid.
function wfu_before_file_upload_handler($file_path, $file_unique_id) {
    // Add code here...
    return $file_path;
}

wfu_before_email_notification

It is executed before email notification is sent, in order to allow advanced checks or modifications to the email. You can use it as follows:

add_filter('wfu_before_email_notification', 'wfu_before_email_notification_handler', 10, 2);

//The following function takes two parameters, $changable_data and $additional_data.
//  $changable_data is an array that can be modified by the filter and contains the items:
//    recipients: the list of recipients (before dynamic variables are applied)
//    subject: the email subject (before dynamic variables are applied)
//    message: the email body (before dynamic variables are applied)
//    headers: the email headers, if exist (before dynamic variables are applied)
//    user_data: an array of user data values, if userdata are activated
//    filename: a comma separated list of uploaded file names (only the file names)
//    filepath: a comma separated list of uploaded file paths (absolute full file paths)
//    error_message: initially it is set to an empty value, if the handler sets a non-empty value then email sending will be cancelled showing this error message (message will be shown only to administrators if adminmessages attribute has been activated)
//  $additional_data is an array with additional data to be used by the filter (but cannot be modified) as follows:
//    shortcode_id: this is the id of the plugin, as set using uploadid attribute; it can be used to apply this filter only to a specific instance of the plugin (if it is used in more than one pages or posts)
//The function must return the final $changable_data.
function wfu_before_email_notification_handler($changable_data, $additional_data) {
    // Add code here...
    return $changable_data;
}

wfu_after_file_upload

It is executed after the upload process for each individual file has finished, in order to allow additional actions to be executed (such as define custom javascript code to be executed in client's browser after file upload). You can use it as follows:

add_filter('wfu_after_file_upload', 'wfu_after_file_upload_handler', 10, 2);

//The following function takes two parameters, $changable_data and $additional_data.
//  $changable_data is an array that can be modified by the filter and contains the items:
//    ret_value: not used for the moment, it exists for future additions
//    js_script: javascript code to be executed on the client's browser after each file is uploaded
//  $additional_data is an array with additional data to be used by the filter (but cannot be modified) as follows:
//    shortcode_id: this is the id of the plugin, as set using uploadid attribute; it can be used to apply this filter only to a specific instance of the plugin (if it is used in more than one pages or posts)
//    file_unique_id: this id is unique for each individual file upload and can be used to identify each separate upload
//    upload_result is the result of the upload process:
//      success: the upload was successful
//      warning: the upload was successful but with warning messages
//      error: the upload failed
//    error_message: contains warning or error messages generated during the upload process
//    admin_messages: contains detailed error messages for administrators generated during the upload process
//The function must return the final $changable_data.
function wfu_after_file_upload_handler($changable_data, $additional_data) {
    // Add code here...
    return $changable_data;
}

The following actions are supported:

wfu_after_file_upload

It is executed after the upload process for each individual file has finished, in order to allow additional actions to be executed. You can use it as follows:

add_action('wfu_after_file_upload', 'wfu_after_file_upload_handler', 10, 4);
(It is noted that this action will be removed in future version of the plugin, it is here only for compatibility with previous versions of the plugin, please use wfu_after_file_upload filter instead)

//The following function takes four parameters, $file_unique_id, $upload_result, $error_message and $error_admin_messages.
//  $file_unique_id is is unique for each individual file upload and can be used to identify each separate upload.
//  $upload_result is the result of the upload process:
//    success: the upload was successful
//    warning: the upload was successful but with warning messages
//    error: the upload failed
//  $error_message: contains warning or error messages generated during the upload process
//  $admin_messages: contains detailed error messages for administrators generated during the upload process
//If additional data are required (such as user id, userdata or filename) you can get them by implementing the previous filters
//wfu_before_file_check or wfu_before_file_upload and link both filters by $file_unique_id parameter.
function wfu_after_file_upload_handler($file_unique_id, $upload_result, $error_message, $error_admin_messages) {
    // Add code here...
}

Requirements

The plugin requires to have Javascript enabled in your browser. For Internet Explorer you also need to have Active-X enabled. Please note that old desktop browsers or mobile browsers may not support all of the plugin's features. In order to get full functionality use the latest versions of browsers, supporting HTML5, AJAX and CSS3.

Requires: 2.9.2 or higher
Compatible up to: 4.2.2
Last Updated: 2015-7-2
Active Installs: 10,000+

Ratings

4.3 out of 5 stars

Support

12 of 23 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

1 person says it works.
0 people say it's broken.

100,1,1
0,1,0
50,2,1
50,2,1
100,1,1
100,1,1
50,2,1
100,1,1 100,1,1