README

The Uploader Plugin extends WinterCMS with a backend-managed upload system and frontend components for user file submission.
Editors create so-called "Upload Forms" in the backend and optionally assign which users are allowed to upload to each form.
Frontend pages or blocks reference these backend-defined forms using their Form ID, and optionally include a User ID for controlled access.

⚙️ Overview

This plugin provides:

• Backend-defined upload forms (with user access lists).
• A frontend upload component bound to a backend form.
• QR code generators linking directly to upload pages.
• Email notifications after successful uploads.
• Themed .blocks for UIKit and Bootstrap frontends.

All upload logic depends on backend definitions — no form can function until it has been created there.

📦 Installation

Install the plugin via Composer:

composer require mercator/wn-uploader-plugin

Then apply database migrations:

php artisan winter:up

🧠 Concept

🧩 CMS Component: Uploader

Purpose

Renders a frontend upload form connected to a backend-defined upload form. Files are stored in the media folder. Note that files are NOT automatically deleted when the Upload Form is deleted.

Usage

In your CMS page or layout:

[Uploader]
formId = "ajnjcdshu73nsd"
userId = "mdswedjndso734jdsi832j"

Then in the page markup:

{% component 'uploader' %}

Parameters

Example Twig Rendering

<div class="upload-section">
    {% component 'uploader' %}
</div>

If a form is missing or access is denied, the component displays:

“Upload form not found or user not permissioned.”

🧱 Pre-defined Blocks

Located in /blocks/, these provide ready-made upload and QR-code functionality. Each block references the backend Form ID and automatically enforces form permissions.

🧮 Backend Usage

1. Upload Forms

Go to Uploader in the backend.

Each Upload Form contained there defines:

• A unique Form ID
• Title and Description shown in frontend blocks and components
• Allowed users, identified by name, email, or ID
• Upload constraints (file size, extensions, ...)
• Notification email settings

Once created, the form can be referenced in frontend on CMS pages or using WinterCMS Blocks, both described above.

2. Access Control

User access can be defined per upload form. Each form specifies which users are authorized to upload.

Permission can be validated via:

uploaderUserIsPermissioned(form_id, user_id)

If the form does not exist or access is restricted and the user in not on the allowed list, the upload form is not displayed.

3. Email Notifications

Each upload form can optionally send email notifications to instruct them on file uplaoding and provide them with credentials. Notifications are sent to the authorized user defined in the form. The email will provide a link where the user will be able to upload his or her files.

4. Limitations for HEIF/HEIC

HEIF/HEIC images can be uploaded provided heif/heic are specified as allowed file extensions in the backend. In this caase, resizing and editing wll not be available for these types. Note that browsers do not support thse image types. Thefore a conversion libray will be lazy-loaded when such images are uploaded. This library is rather large and might into your bandwidth.

🔐 Access Summary

All checks are enforced server-side.

🧰 Developer Notes

• Compatible with the dev instance of WinterCMS 1.2.8 and PHP 8.3
• Uses System\Models\File for file storage
• Works with both UIKit and Bootstrap
• Helper functions:
  • uploaderForm(form_id)
  • uploaderUserIsPermissioned(form_id, user_id)
  • uploaderQRCode(url, size, margin)
  • uploaderUploaderOpen(form_id [, user_id]) returns 0 when upload is authorized.

📄 License

MIT License. See LICENSE for details.

👤 Author

Helmut Kaufmann, Küssnacht am Rigi, Switzerland, software@mercator.li mercator.li