wp-file-upload-security

WordPress File Upload Security

Treat an upload as untrusted bytes plus attacker-controlled metadata. Use the core upload pipeline, then apply a narrower product policy; extension/MIME matching alone is not malware scanning or content safety.

Choose the flow

Do not manually combine move_uploaded_file(), a client MIME, and the original name when core already provides unique naming, upload checks, and hooks.

WordPress 7.1 also supports browser-side image processing and new REST flows for dimension validation, size-aware quality, and registering one sideloaded file for multiple sizes. This changes where bytes may be transformed, not the trust boundary: server-side capability, intent, MIME/dimension/resource checks, metadata validation, and cleanup remain mandatory. Use wp-client-side-media-processing for that protocol.

Browser-to-Media-Library pattern

The form needs method="post" and enctype="multipart/form-data". The handler owns authorization and request intent before touching $_FILES.

function myplugin_handle_document_upload() {
    if ( ! current_user_can( 'upload_files' ) ) {
        return new WP_Error( 'myplugin_forbidden', __( 'Upload not allowed.', 'myplugin' ) );
    }
    check_admin_referer( 'myplugin_upload_document' );

    if ( empty( $_FILES['myplugin_document'] )
         || ! is_array( $_FILES['myplugin_document'] ) ) {
        return new WP_Error( 'myplugin_missing_upload', __( 'Choose a file.', 'myplugin' ) );
    }

    $file = $_FILES['myplugin_document'];
    if ( UPLOAD_ERR_OK !== (int) ( $file['error'] ?? UPLOAD_ERR_NO_FILE ) ) {
        return new WP_Error( 'myplugin_upload_error', __( 'Upload failed.', 'myplugin' ) );
    }

    $max = min( wp_max_upload_size(), 5 * MB_IN_BYTES );
    if ( (int) ( $file['size'] ?? 0 ) < 1 || (int) $file['size'] > $max ) {
        return new WP_Error( 'myplugin_upload_size', __( 'Invalid file size.', 'myplugin' ) );
    }

    $mimes = array(
        'pdf' => 'application/pdf',
        'jpg|jpeg' => 'image/jpeg',
        'png' => 'image/png',
    );
    $checked = wp_check_filetype_and_ext(
        (string) $file['tmp_name'],
        (string) $file['name'],
        $mimes
    );

    // Enforce this feature's policy even for users with unfiltered_upload.
    if ( empty( $checked['ext'] ) || empty( $checked['type'] ) ) {
        return new WP_Error( 'myplugin_upload_type', __( 'File type not allowed.', 'myplugin' ) );
    }

    require_once ABSPATH . 'wp-admin/includes/file.php';
    require_once ABSPATH . 'wp-admin/includes/media.php';
    require_once ABSPATH . 'wp-admin/includes/image.php';

    $attachment_id = media_handle_upload(
        'myplugin_document',
        0,
        array(),
        array( 'test_form' => false, 'mimes' => $mimes )
    );

    if ( is_wp_error( $attachment_id ) ) {
        return $attachment_id;
    }

    return (int) $attachment_id;
}