File Uploads & Downloads

Larajax provides simple features for managing files, uploading files through form submissions or downloading files through response types. These features are opt-in to the AJAX framework for the best performance.

Downloading Files

To enable file downloads, include the data-request-download attribute on a HTML form or button tag. The following is a minimal example of downloading a file.

<button
    data-request="onDownload"
    data-request-download>
    Download
</button>

If the data-request-download="..." attribute is set on the request trigger, the filename in this attribute will be given to the downloaded file. The following produces a file named data.csv.

<button
    data-request="onDownload"
    data-request-download="data.csv">
    Download Document
</button>

To open the file in a new browser window, typically used for previewing PDFs, set the data-browser-target attribute to _blank.

<button
    data-request="onDownload"
    data-request-download
    data-browser-target="_blank">
    Open in New Window
</button>

Download Responses

Inside your AJAX handler, you may use the typical Laravel response type to return a file download response type where the download method accepts the local disk file path.

public function onDownload()
{
    return response()->download(base_path('app/files/installer.zip'));
}

To convert a string to a downloadable response without having to write the contents to disk, use the streamDownload method, which accepts a callback (first argument) and filename (second argument).

public function onDownload()
{
    return response()->streamDownload(function() {
        echo 'CSV Contents...';
    }, 'export.csv');
}

Uploading Files

To enable file uploads on a form, include the data-request-files attribute on a HTML form tag. The following is a minimal example uploading a file.

<form data-request="onUploadFiles" data-request-files>
    <div>
        <label>Single File</label>
        <input name="single_file" type="file">
    </div>

    <button data-attach-loading>
        Upload
    </button>
</form>

Inside your AJAX handler, use the files() helper function to access the uploaded file, and call the store method to save the file to a storage disk. The resulting value is the local file path to the saved file.

The following stores the upload in the storage/app/userfiles directory using a generated file name.

function onUploadFiles()
{
    $filePath = request()->file('single_file')->store('userfiles');
}

Uploading Multiple Files

When the multiple attribute is included with the file input, the files() helper will return an array instead.

<div>
    <label>Multi File</label>
    <input name="multi_file[]" type="file" multiple>
</div>

function onUploadFiles()
{
    $filePaths = [];

    foreach (request()->file('multi_file') as $file) {
        $filePaths[] = $file->store('userfiles');
    }

    // ...
}

Validating File Uploads

Just like regular form validation, files can be validated using the request() helper and validate method. Use the .* suffix when validating multiple items. The following checks that the uploaded file is an image and not greater than 1MB in size.

function onUploadFiles()
{
    request()->validate([
        'single_file' => 'required|image|max:1024',
        'multi_file.*' => 'required|image|max:1024',
    ]);
}