Add filters for file uploads (prepare and pre upload), update PHPDoc

[tripflex]

This PR adds two new filters in the file upload handling process.

The first filter job_manager_prepare_uploaded_files is added to the return value from the core function job_manager_prepare_uploaded_files (this I added so it's available if needed later)

The second filter and the most important one is the job_manager_upload_file_pre_upload filter added before the core wp_handle_upload function is called.

This allows us to check the file for certain conditions (file size, dimensions, etc), or anything else that may be required before actually uploading the file, and return our own WP_Error that would then be output on the frontend (in error notice, or message box for Ajax uploads).

The most important part of this is that it prevents the file from actually being uploaded to the server, as the only method I can use right now is in the validation process and return an error, but by that point the file has already been uploaded to the server.

[tripflex]

IMO this is a really important filter that is missing as I could use the submit_job_wp_handle_upload_overrides which I actually added in a PR a long time ago, but that was before the upload handling was changed, and we need to be able to return our own WP_Error to specify to the user on frontend what the problem was

[tripflex]

Also updated PHPDoc as return value is going to be stdClass or WP_Error object

[kraftbj]

Incredibly picky, but can you add the space after the if?

I'm not crazy about the readability of the line, but not a blocker for me.

[spencerfinnell]

I would say pull out the whole $file var.

[tripflex]

@spencerfinnell nah this way by adding one filter we add two use case scenarios ... one for modifying the $file data before being uploaded, and the other for returning a WP_Error to prevent upload and return that error

[kraftbj]

Noted very nit-picky code standard fix, but otherwise, 👍 from me.

[tripflex]

@kraftbj Would you prefer something like this instead?

/**
 * Filter file configuration before upload
 *
 * This filter can be used to modify the file arguments before being uploaded, or return a WP_Error
 * object to prevent the file from being uploaded, and return the error.
 *
 * @since 1.25.2
 *
 * @param array $file Array of $_FILE data to upload.
 * @param array $args Optional file arguments
 * @param array $allowed_mime_types Array of allowed mime types from field config or defaults
 */
$file = apply_filters( 'job_manager_upload_file_pre_upload', $file, $args, $allowed_mime_types );

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

[tripflex]

I used the method in the PR to kind of mimic this:

// Validate required
if ( is_wp_error( ( $return = $this->validate_fields( $values ) ) ) ) {
    throw new Exception( $return->get_error_message() );
}

https://github.com/Automattic/WP-Job-Manager/blob/master/includes/forms/class-wp-job-manager-form-submit-job.php#L426-L429

[kraftbj]

Yeah, that docblock is good. Commit it and I'll merge this in.

[tripflex]

@kraftbj okay updated