# Filesystem and Uploads

The framework includes Dbm\Infrastructure\Filesystem\Filesystem for common local filesystem operations and two image-upload helpers under Dbm\Infrastructure\Upload. These are utilities, not a virtual filesystem or a complete upload-security policy.

# Filesystem

Inject Filesystem where file operations are needed. It provides file and directory checks, reads and writes, copy/rename/delete operations, directory listing and recursion, path normalization, and moving a PHP-uploaded temporary file.

$contents = $filesystem->readFile($path); // string|null
$filesystem->saveFile($path, $contents);
$filesystem->ensureDir(dirname($path));
$files = $filesystem->listFiles($directory, '.json');

Some operations return null or an empty list when a path is absent; write/copy operations can throw RuntimeException. moveUploadedFile() checks is_uploaded_file() before calling move_uploaded_file(). Methods operate on the paths supplied by the caller: constrain paths to an application-owned root, validate authorization, and do not treat path normalization as a sandbox.

# UploadImage

UploadImage::uploadImage() accepts a PHP upload array (for example, one item from $_FILES). Defaults allow JPG/JPEG, PNG, GIF, and WebP up to 6 MiB. You can configure the target directory, allowed extensions, maximum size and dimensions, collision-renaming behavior, and message translations. It returns an array with status, message, and (on success) a stored filename in data.

$upload = new UploadImage();
$upload->setTargetDir(Paths::joinPaths(Paths::basePath(), 'storage', 'uploads'));
$upload->setAllowedTypes(['jpg', 'png', 'webp']);
$upload->setMaxFileSize(4 * 1024 * 1024);
$upload->setMaxWidth(2400);
$upload->setMaxHeight(2400);
$upload->setRenameIfExist(true);

$result = $upload->uploadImage($_FILES['image'] ?? []);
if ($result['status'] !== 'success') {
    // Show or log the validation message; do not expose internal paths.
}

The helper checks the uploaded structure, size, extension and image dimensions, then moves the upload. Store uploads outside executable/public paths when possible, set restrictive permissions, and add application-specific authorization and content checks.

# ResizeUploadImage

ResizeUploadImage::createImages() stores generated image variants beneath original/, photo/, and thumb/ subdirectories of the target directory. It validates a set of image extensions and size, generates a sanitized unique filename, enforces a default minimum image width of 960 pixels, and resizes the photo and thumbnail. The original file is removed after successful processing. This helper requires the PHP GD extension.

Its setters configure maximum upload size, photo width, thumbnail width, image quality, and message translations. Treat the returned status/message/data array as the operation result and check it before using the resulting filename. Image decoding and filesystem permissions must be available in the deployment.