Using WordPress ‘pre_upload_error’ PHP filter

The ‘pre_upload_error’ filter allows you to intercept an XML-RPC media upload in WordPress and return a custom error response. By returning a truthy value, you can stop the media upload process and return a 500 error with your custom message.

Usage

To use this filter, add your custom function to the ‘pre_upload_error’ filter hook:

add_filter( 'pre_upload_error', 'your_custom_function', 10, 1 );

function your_custom_function( $error ) {
    // Your custom logic here
}

Parameters

  • $error (bool): Whether to pre-empt the media upload. Default is false.

Examples

Limiting file size

add_filter( 'pre_upload_error', 'limit_file_size', 10, 1 );

function limit_file_size( $error ) {
    $max_size = 500000; // 500KB
    $file_size = $_FILES['file']['size'];

    if ( $file_size > $max_size ) {
        return new WP_Error( 'file_size_exceeded', 'The file size exceeds the limit.' );
    }

    return $error;
}

In this example, we limit the file size of an uploaded media file to 500KB. If the file size exceeds the limit, a custom error message is returned.

Restrict file types

add_filter( 'pre_upload_error', 'restrict_file_types', 10, 1 );

function restrict_file_types( $error ) {
    $allowed_extensions = array( 'jpg', 'jpeg', 'png', 'gif' );
    $file_extension = pathinfo( $_FILES['file']['name'], PATHINFO_EXTENSION );

    if ( ! in_array( strtolower( $file_extension ), $allowed_extensions ) ) {
        return new WP_Error( 'invalid_file_type', 'Invalid file type. Only jpg, jpeg, png, and gif files are allowed.' );
    }

    return $error;
}

In this scenario, we restrict the uploaded media file types to JPG, JPEG, PNG, and GIF. If the file type does not match, a custom error message is returned.

Limit uploads for specific users

add_filter( 'pre_upload_error', 'limit_uploads_for_user', 10, 1 );

function limit_uploads_for_user( $error ) {
    $restricted_user = 'john_doe';
    $current_user = wp_get_current_user();

    if ( $restricted_user === $current_user->user_login ) {
        return new WP_Error( 'uploads_not_allowed', 'You are not allowed to upload media.' );
    }

    return $error;
}

This example restricts media uploads for a specific user by their username. If the user tries to upload a file, a custom error message is returned.

Check upload time

add_filter( 'pre_upload_error', 'limit_upload_time', 10, 1 );

function limit_upload_time( $error ) {
    $allowed_hours = range( 9, 17 );

    if ( ! in_array( intval( date( 'G' ) ), $allowed_hours ) ) {
        return new WP_Error( 'uploads_not_allowed_time', 'Media uploads are allowed only between 9 AM and 5 PM.' );
    }

    return $error;
}

In this example, we limit the media uploads to a specific time range. If a user tries to upload a file outside the allowed hours, a custom error message is returned.

Limit uploads based on user role

add_filter( 'pre_upload_error', 'limit_uploads_for_role', 10, 1 );

function limit_uploads_for_role( $error ) {
    $restricted_role = 'subscriber';
    $current_user = wp_get_current_user();

    if ( in_array( $restricted_role, $current_user->roles ) ) {
        return new WP_Error( 'uploads_not_allowed_role', 'Subscribers are not allowed to upload media.' );
    }

    return $error;
}

In this scenario, we restrict media uploads for users with a specific role. If a user with the ‘subscriber’ role tries to upload a file, a custom error message is returned.