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:
| Key | Meaning |
|---|---|
upload.invalid_format | Not valid base64, or the MIME type is not in the allow list |
upload.exceeded_file_size | Larger than UPLOAD.maxsize.image |
upload.failed_to_move | The 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.