Controlling How Multi-File Uploaders Behave

Trongate's multi-file (drag 'n' drop) uploader certainly achieves a lot with virtually no real work.  By default, it comes with token-based authorization and it makes sure the user attempting the upload (or the delete) has a role of 'admin'.

That's all well and good.   However, there may be instances where you'd like to modify how your multi-file uploaders behave.  For example;

• Perhaps you'd like to set your own custom authorization rules for the multi-file uploader
  
• Perhaps you'd like to run tests on individual files before allowing them to be uploaded
  

All of this is possible.  Before we get into this, let's have a quick reminder of how file uploading - and the multi-file uploader in particular works.

How The Multi-File Uploader Works

When you attempt to upload some files, using the multi-file uploader, each file is posted to an endpoint.  The endpoint is the BASE_URL followed by trongate_filezone/upload, followed by a few other segments.

This means that each and every file that a user selects (or drops) is going to initiate an HTTP Post request.  This post request gets received by the 'trongate_filezone' module.

Unlike with ordinary form submissions, the information relating to the submitted file (in this case an image) is available in the $_FILES superglobal.  The $_FILES superglobal is a special array, containing information about files that have been submitted.

If you have a look at the Trongate_filezone.php controller file, you'll notice that the upload() method starts with the line:

api_auth();

The api_auth() command tells Trongate to enforce any authorization rules that have been declared inside the api.json file, within the trongate_filezone module.  By default, the upload method comes with the following settings (inside api.json):

"Upload": {
    "url_segments": "trongate_filezone/upload/{target_module}/{update_id}",
    "request_type": "POST",
    "description": "The endpoint for gallery uploads.",
    "enableParams": false,
    "required_fields": [
        {
            "name": "update_id",
            "label": "Update ID"
        },
        {
            "name": "target_module",
            "label": "Target Module"
        }
    ],
    "authorization":{
        "roles": [
            "admin"
        ]
    }
  }

As you can see, by default the trongate_filezone module enforces the rule that only users with a role of 'admin' are allowed upload to upload files.

Modifying Authorization Rules

Having api_auth() declared means that developers have Trongate's API Authorization protocol fully enabled.  Comprehensive documentation on how this works can be found: here.

A type of API authorization that is particularly noteworthy is User Owned Segment Authorization.  This is a type of authorization that could be used to restrict uploads to only users who own or have been assigned to a particular record.

Below is an example of some custom authorization rules that grant access to:

• users with a role of 'admin'
• users who have been assigned to target records

"authorization":{
    "roles": [
        "admin"
    ],
    "userOwnedSegment": {
        "column": "id",
        "segmentNum": 4
    }
}

Running Validation Tests On Submitted Files

The business of uploading pictures is carried out by a method named '_do_upload'.  This method resides inside the trongate_filezone module.

The do_upload() method follows the normal image uploading protocol for Trongate.  Once it has finished uploading, it sends an HTTP response code of 200.

http_response_code(200);

This 200 response code indicates that everything went well.  From an end-user perspective, we then see a green background appear on the thumbnail of the uploaded image.  This is our confirmation that the upload was successful.

If you'd like to run validation tests on submitted files then the key is to be able to access the $_FILES superglobal.  

Here's an example of how to fetch a submitted picture's width:

$submitted_file = array_keys($_FILES)[0];
$temp_file_name = $_FILES[$submitted_file]['tmp_name'];
$dimension_data = getimagesize($temp_file_name);
$width = $dimension_data[0];

Being able to access the properties of a submitted image gives us an opportunity to test for things like maximum width.  If an image fails one of our tests - for example by being too wide then we could return an HTTP Response Status Code of 401 echo out 'too wide' (or a similar message).  Doing this will give thumbnails a red background, indicating that the image was not uploaded.