271 lines
12 KiB
PHP
271 lines
12 KiB
PHP
<?php
|
|
|
|
/**
|
|
* FileUploader
|
|
*
|
|
* Handles secure file upload, validation, cleanup, and rollback for
|
|
* the WMS application. Designed to be used with any form that accepts
|
|
* image or PDF attachments (product images, contact photos, etc.).
|
|
*
|
|
* Typical usage flow:
|
|
* 1. Instantiate with the absolute server path to the upload directory.
|
|
* 2. Call cleanup() to delete files the user removed in the UI.
|
|
* 3. Call upload() to validate and move new files from $_FILES.
|
|
* 4. If DB write succeeds, call buildFileString() to persist the final CSV.
|
|
* 5. If DB write fails, call rollbackUploads() to delete the newly uploaded files.
|
|
*
|
|
* Example:
|
|
* $uploader = new FileUploader('/var/www/app/uploads/products/');
|
|
* $uploader->cleanup($existing_files_csv, $kept_files_csv);
|
|
* $errors = $uploader->upload('product_image');
|
|
* if (empty($errors)) {
|
|
* $file_string = $uploader->buildFileString($kept_files_csv);
|
|
* // save $file_string to DB...
|
|
* } else {
|
|
* $uploader->rollbackUploads();
|
|
* }
|
|
*
|
|
* Security:
|
|
* - Validates both file extension and MIME type via finfo (double-check).
|
|
* - Sanitises original filename before use; replaces non-alphanumeric characters with '_'.
|
|
* - Generates a unique filename with uniqid() to prevent overwrite attacks.
|
|
* - Sets uploaded files to 0644 permissions (web-readable, not executable).
|
|
* - Rejects any file exceeding the 5MB size limit.
|
|
*/
|
|
class FileUploader {
|
|
|
|
private $target_dir;
|
|
private $allowed_mimes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'application/pdf'];
|
|
private $allowed_extensions = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'pdf'];
|
|
private $max_size = 5 * 1024 * 1024; // 5MB
|
|
private $uploaded_files = []; // filenames of files successfully uploaded in this request
|
|
private $deleted_files = []; // filenames of files deleted from disk in this request
|
|
|
|
/**
|
|
* Initialise the uploader for a specific directory.
|
|
*
|
|
* Creates the directory if it does not exist (recursive, 0755).
|
|
* Throws if the directory cannot be created or is not writable.
|
|
*
|
|
* @param string $target_dir Absolute path to the upload directory (trailing slash optional).
|
|
* @throws Exception If the directory cannot be created or is not writable.
|
|
*/
|
|
public function __construct($target_dir) {
|
|
$this->target_dir = rtrim($target_dir, '/') . '/';
|
|
$this->ensureDirectory();
|
|
}
|
|
|
|
// ─────────────────────────────────────────────────────────────
|
|
// Public — cleanup
|
|
// ─────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Delete files that the user removed in the UI.
|
|
*
|
|
* Compare the original comma-separated file list ($existing_csv) against
|
|
* the files the user chose to keep ($keep_csv). Any file in $existing but
|
|
* not in $keep is deleted from disk.
|
|
*
|
|
* Call this BEFORE upload() so that freed space is available and the
|
|
* $deleted_files list is populated before any rollback is needed.
|
|
*
|
|
* @param string $existing_csv Comma-separated filenames previously stored in DB.
|
|
* @param string $keep_csv Comma-separated filenames the user kept in the form.
|
|
*/
|
|
public function cleanup($existing_csv, $keep_csv) {
|
|
if (empty($existing_csv)) return;
|
|
|
|
$existing = array_filter(array_map('trim', explode(',', $existing_csv)));
|
|
$keep = !empty($keep_csv)
|
|
? array_filter(array_map('trim', explode(',', $keep_csv)))
|
|
: [];
|
|
|
|
foreach ($existing as $file) {
|
|
if (!in_array($file, $keep)) {
|
|
$path = $this->target_dir . $file;
|
|
if (file_exists($path)) {
|
|
unlink($path);
|
|
$this->deleted_files[] = $file;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// ─────────────────────────────────────────────────────────────
|
|
// Public — upload
|
|
// ─────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Validate and move uploaded files from $_FILES to the target directory.
|
|
*
|
|
* Handles both single-file and multi-file inputs transparently.
|
|
* Each file is validated for:
|
|
* - PHP upload error code (UPLOAD_ERR_OK)
|
|
* - File size (≤ max_size, default 5MB)
|
|
* - File extension (whitelist)
|
|
* - MIME type via finfo (double-check against extension spoofing)
|
|
*
|
|
* Successfully uploaded files are tracked in $this->uploaded_files and
|
|
* can be rolled back via rollbackUploads() if the DB write later fails.
|
|
*
|
|
* @param string $field_name The $_FILES key (HTML input name attribute).
|
|
* @return array Array of human-readable error strings. Empty array = all files accepted.
|
|
*/
|
|
public function upload($field_name) {
|
|
if (!isset($_FILES[$field_name])) return [];
|
|
|
|
$errors = [];
|
|
|
|
// Normalise single-file $_FILES entry to array structure
|
|
$files = $_FILES[$field_name];
|
|
if (!is_array($files['name'])) {
|
|
$files['name'] = [$files['name']];
|
|
$files['tmp_name'] = [$files['tmp_name']];
|
|
$files['error'] = [$files['error']];
|
|
$files['size'] = [$files['size']];
|
|
}
|
|
|
|
foreach ($files['name'] as $key => $name) {
|
|
$error_code = $files['error'][$key];
|
|
|
|
if ($error_code !== UPLOAD_ERR_OK) {
|
|
$errors[] = "{$name}: " . $this->getUploadError($error_code);
|
|
continue;
|
|
}
|
|
|
|
$tmp_name = $files['tmp_name'][$key];
|
|
$file_size = $files['size'][$key];
|
|
$extension = strtolower(pathinfo($name, PATHINFO_EXTENSION));
|
|
|
|
// Size check
|
|
if ($file_size > $this->max_size) {
|
|
$errors[] = "{$name}: exceeds " . ($this->max_size / 1024 / 1024) . "MB limit";
|
|
continue;
|
|
}
|
|
|
|
// Extension whitelist check
|
|
if (!in_array($extension, $this->allowed_extensions)) {
|
|
$errors[] = "{$name}: .{$extension} is not allowed";
|
|
continue;
|
|
}
|
|
|
|
// MIME type check via finfo (cannot be spoofed by renaming)
|
|
$finfo = finfo_open(FILEINFO_MIME_TYPE);
|
|
$mime = finfo_file($finfo, $tmp_name);
|
|
finfo_close($finfo);
|
|
|
|
if (!in_array($mime, $this->allowed_mimes)) {
|
|
$errors[] = "{$name}: content type ({$mime}) is not allowed";
|
|
continue;
|
|
}
|
|
|
|
// Sanitise original filename and generate a unique destination name
|
|
$original = pathinfo($name, PATHINFO_FILENAME);
|
|
$original = preg_replace('/[^a-zA-Z0-9_-]/', '_', $original);
|
|
$file_id = $original . '_' . uniqid() . '.' . $extension;
|
|
$destination = $this->target_dir . $file_id;
|
|
|
|
if (move_uploaded_file($tmp_name, $destination)) {
|
|
$this->uploaded_files[] = $file_id;
|
|
chmod($destination, 0644); // web-readable, not executable
|
|
} else {
|
|
$errors[] = "{$name}: failed to save";
|
|
}
|
|
}
|
|
|
|
return $errors;
|
|
}
|
|
|
|
// ─────────────────────────────────────────────────────────────
|
|
// Public — result helpers
|
|
// ─────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Build the final comma-separated filename string for DB storage.
|
|
*
|
|
* Merges the files the user kept ($keep_csv) with any newly uploaded
|
|
* files from this request, and returns them as a single CSV string.
|
|
* Pass this return value to the DB column that stores file references.
|
|
*
|
|
* @param string $keep_csv Comma-separated filenames the user kept in the form.
|
|
* @return string Final comma-separated file list ready for DB storage.
|
|
*/
|
|
public function buildFileString($keep_csv) {
|
|
$keep = !empty($keep_csv)
|
|
? array_filter(array_map('trim', explode(',', $keep_csv)))
|
|
: [];
|
|
$final = array_merge($keep, $this->uploaded_files);
|
|
return implode(",", array_filter($final));
|
|
}
|
|
|
|
/**
|
|
* Return the list of filenames successfully uploaded in this request.
|
|
*
|
|
* Useful when only a single image field is expected and you need to
|
|
* retrieve the stored filename directly without building a CSV string.
|
|
*
|
|
* @return array Flat array of uploaded filenames (may be empty).
|
|
*/
|
|
public function getUploadedFiles() {
|
|
return $this->uploaded_files;
|
|
}
|
|
|
|
/**
|
|
* Delete all files uploaded in this request — call if the DB write fails.
|
|
*
|
|
* Ensures no orphaned files remain on disk when a transaction is rolled back.
|
|
* Safe to call multiple times (idempotent if files are already gone).
|
|
* After rollback, $this->uploaded_files is cleared.
|
|
*/
|
|
public function rollbackUploads() {
|
|
foreach ($this->uploaded_files as $file) {
|
|
$path = $this->target_dir . $file;
|
|
if (file_exists($path)) {
|
|
unlink($path);
|
|
}
|
|
}
|
|
$this->uploaded_files = [];
|
|
}
|
|
|
|
// ─────────────────────────────────────────────────────────────
|
|
// Private helpers
|
|
// ─────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Create the target directory if it does not exist, and verify it is writable.
|
|
*
|
|
* @throws Exception If mkdir fails or the directory is not writable.
|
|
*/
|
|
private function ensureDirectory() {
|
|
if (!is_dir($this->target_dir)) {
|
|
if (!mkdir($this->target_dir, 0755, true)) {
|
|
throw new Exception("Failed to create directory: " . $this->target_dir);
|
|
}
|
|
}
|
|
if (!is_writable($this->target_dir)) {
|
|
throw new Exception("Target directory is not writable: " . $this->target_dir);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Convert a PHP upload error code into a human-readable message.
|
|
*
|
|
* Covers all UPLOAD_ERR_* constants defined by PHP.
|
|
* Falls back to a generic message for unknown codes.
|
|
*
|
|
* @param int $code A UPLOAD_ERR_* constant value.
|
|
* @return string Human-readable error description.
|
|
*/
|
|
private function getUploadError($code) {
|
|
$messages = [
|
|
UPLOAD_ERR_INI_SIZE => "exceeds server max upload size (" . ini_get('upload_max_filesize') . ")",
|
|
UPLOAD_ERR_FORM_SIZE => "exceeds form max size",
|
|
UPLOAD_ERR_PARTIAL => "was only partially uploaded",
|
|
UPLOAD_ERR_NO_FILE => "no file was sent",
|
|
UPLOAD_ERR_NO_TMP_DIR => "server missing temp folder",
|
|
UPLOAD_ERR_CANT_WRITE => "server failed to write to disk",
|
|
UPLOAD_ERR_EXTENSION => "blocked by server extension",
|
|
];
|
|
return $messages[$code] ?? "unknown error (code {$code})";
|
|
}
|
|
} |