File Management

This document describes the file management subsystem in the Hotelaro codebase. It covers the mechanisms for uploading, validating, and storing files (including images and documents), as well as the related frontend and backend code entities. The focus is on the technical implementation, including single and multi-file upload flows, file validation, and storage conventions.

For information about general-purpose helper functions, see Common Helpers. For details on form submission, validation, and notifications, see Form Handling.

Purpose and Scope

This page documents:

File upload flows (single and multiple files)
Image and document handling
File validation (type, size)
Storage paths and conventions
Key backend controllers and frontend scripts involved

It does not cover:

General asset management for themes or static resources (see Frontend Website)
Form validation and AJAX notification systems (see Form Handling)

System Overview

The file management system enables users (typically admins) to upload images and documents through the web interface. Uploaded files are validated, stored in a structured directory under writable/uploads/, and their paths are returned for further use (e.g., displaying images, attaching documents to records).

High-Level Flow Diagram

Key Code Entities

Entity	Type	Location	Description
FileorImageUploadController	Controller	app/Controllers/FileorImageUploadController.php	Handles single and multi-file upload endpoints, validation, and storage.
imageorfileupload.php	View/Script	app/Views/common_script/imageorfileupload.php	Frontend JS for single file/image upload.
multifileuploader.php	View/Script	app/Views/common_script/multifileuploader.php	Frontend JS for multi-file/image upload.
writable/uploads/	Directory	(filesystem)	Storage location for uploaded files, organized by type.

Backend: File Upload Controller

The main backend logic is implemented in the FileorImageUploadController class.

Endpoints

singleuploader(): Handles single file/image upload.
multiuploader(): Handles multiple file/image uploads.

Validation Logic

File type: Only allows specific extensions based on filetype parameter (image: jpg, jpeg, png, webp; document: pdf, xls, xlsx).
File size: Maximum 5 MB per file.
Storage: Files are stored in writable/uploads/{filetype}/ with a random name.

Example: Single File Upload Flow

"writable/uploads/"
"FileorImageUploadController"
"Frontend JS"
"writable/uploads/"
"FileorImageUploadController"
"Frontend JS"
POST /singleuploader (file, filetype)
Validate filetype, extension, size
Move file to uploads/{filetype}/
JSON {status, filename, message}

Frontend: Upload Scripts

Single File/Image Upload

Implemented in imageorfileupload.php
Binds to an element
On file selection, sends AJAX POST to /singleuploader
On success, updates a hidden input and (optionally) an image preview

Multi-File/Image Upload

Implemented in multifileuploader.php
Binds to an
On file selection, sends AJAX POST to /multiuploader
Handles up to 15 files per upload
Updates a hidden input with JSON array of file info and displays previews

Example: Multi-File Upload UI Update

File Storage Structure

Uploaded files are stored in the following structure:

writable/
└── uploads/
    ├── image/
    │   └── {random_filename}.png
    └── document/
        └── {random_filename}.pdf

The subdirectory is determined by the filetype parameter.

Filenames are randomized to avoid collisions and for security.

File Validation and Error Handling

Validation Step	Logic	Error Response
File present	Checks if file is uploaded	400, "No file was uploaded."
File type	Checks filetype param and extension	400, "Invalid file type provided." or "Invalid file format."
File size	Max 5 MB	400, "File size exceeds the maximum limit of 5 MB."
File validity	Checks for upload errors	400, "Failed to upload the file."

Bridging System Names to Code Entities

Diagram: File Upload System and Code Entities

Example: Integration with Other Systems

Uploaded file paths are typically stored in database fields or used to display images/documents in the admin interface. The file management system is designed to be modular and reusable across different modules (e.g., room images, customer documents).

Security and Best Practices

Only specific file types are allowed, based on context.
File size is strictly limited.
Files are stored outside the web root (writable/), reducing risk of direct access.
Filenames are randomized to prevent enumeration and overwriting.

Summary Table: File Management Endpoints

Endpoint	Method	Purpose	View/Script	Controller Method
/singleuploader	POST	Single file/image upload	imageorfileupload.php	FileorImageUploadController::singleuploader()
/multiuploader	POST	Multi-file/image upload	multifileuploader.php	FileorImageUploadController::multiuploader()