Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

File Upload

Introduction

Sukarix\Helpers\Receiver handles file uploads: validating what the browser sent, checking the real MIME type and size, and moving the file into the uploads directory under a generated name. It covers both multipart form uploads and base64 data URIs (an image cropped in the browser, for instance).

Configuration

The helper is resolved through the Injector under the receiver alias, declared in classes.ini:

[classes]
receiver = Sukarix\Helpers\Receiver

Limits and allowed types live in upload.ini, keyed by MIME type:

[UPLOAD.allowed.mimes]
images[png]  = image/png
images[jpg]  = image/jpeg
images[webp] = image/webp

[UPLOAD.maxsize.image]
value    = 5
exponent = MB

The array key (png, jpg, …) becomes the extension of the stored file, so the extension always matches the detected content rather than whatever name the client chose. UPLOADS (see Configuration) is the directory every stored path is relative to.

Uploading a Base64 Image

uploadImageBase64() accepts a data URI or bare base64 string, decodes it, sniffs the MIME type of the decoded bytes and stores the file under UPLOADS/<sub directory>/<field name><hash>.<ext>:

/** @var Receiver $receiver */
$receiver = Injector::instance()->get('receiver');

$result = $receiver->uploadImageBase64($this->getDecodedBody()['avatar'], 'avatars/', 'avatar');
if (null !== $result['error']) {
    $this->error($this->i18n->err($result['error']), 422);
}

$path = $receiver->uploadedFiles()['avatar']; // 'avatars/avatar1cfmd20afirq4.png'

Every outcome is reported in the returned array rather than thrown. error is null on success, otherwise one of:

KeyMeaning
upload.invalid_formatNot valid base64, or the MIME type is not in the allow list
upload.exceeded_file_sizeLarger than UPLOAD.maxsize.image
upload.failed_to_moveThe file could not be written

The keys are translation keys by design: add them to your dictionaries under i18n.error and pass them straight to the user.

Uploading a Form File

upload() is the equivalent for a $_FILES entry. It is protected, so expose it from your own receiver with the directory, size limit and allow list your application wants:

namespace Helpers;

class Receiver extends \Sukarix\Helpers\Receiver
{
    public function storeDocument(array $file): array
    {
        return $this->upload(
            $file,
            $this->f3->get('UPLOADS') . 'documents',
            10 * 1024 * 1024,
            ['pdf' => 'application/pdf'],
            'document'
        );
    }
}

Register that subclass under the receiver alias instead of the framework’s. upload() rejects corrupt $_FILES entries (upload.invalid_parameters), maps PHP’s own upload errors (upload.no_file, upload.exceeded_file_size, upload.unknown), then applies the same MIME and size checks as above. Pass null for the size limit or the allow list to skip that check. Under Environment::isTest() the file is moved with rename() instead of move_uploaded_file(), so a test can hand it any temporary file.

uploadedFiles() returns every file stored by the receiver during the request, keyed by form field name, as paths relative to UPLOADS — ready to persist on a model.