File Storage Abstraction 💾

<!-- The HTML form. Two non-negotiable attributes for file uploads: -->
<!--   method="post"                  files are too big for the URL -->
<!--   enctype="multipart/form-data"  tells the browser to send raw bytes -->
<form action="upload.php" method="post" enctype="multipart/form-data">
  <!-- name="photo" becomes the key in $_FILES on the server. -->
  <input type="file" name="photo" accept="image/*">
  <button type="submit">Upload</button>
</form>

<?php
// upload.php — what the server receives. Each <input type="file" name="photo">
// arrives as $_FILES["photo"], an array with five keys.

$file = $_FILES["photo"];

echo "name:     " . $file["name"]     . "\n"; // original filename FROM THE USER (untrusted!)
echo "type:     " . $file["type"]     . "\n"; // MIME the BROWSER claims (untrusted!)
echo "tmp_name: " . $file["tmp_name"] . "\n"; // where PHP parked it on disk, temporarily
echo "error:    " . $file["error"]    . "\n"; // 0 means success (see UPLOAD_ERR_* constants)
echo "size:     " . $file["size"]     . "\n"; // size in bytes, measured by PHP (trusted)
?>

name:     holiday.jpg
type:     image/jpeg
tmp_name: /tmp/phpA1b2C3
error:    0
size:     248173

<?php
// Trust NOTHING the browser sends. Validate in this order: error -> size -> MIME.
$file = $_FILES["photo"] ?? null;

// 1) Did the upload even arrive cleanly? error must be UPLOAD_ERR_OK (0).
if ($file === null || $file["error"] !== UPLOAD_ERR_OK) {
    exit("Upload failed (error code " . ($file["error"] ?? "none") . ")\n");
}

// 2) Cap the size. Browsers can lie about type; size from PHP is real.
$maxBytes = 2 * 1024 * 1024;            // 2 MB
if ($file["size"] > $maxBytes) {
    exit("Too big: " . $file["size"] . " bytes (max " . $maxBytes . ")\n");
}

// 3) Detect the REAL MIME by reading the file's bytes — never $file["type"].
$finfo = new finfo(FILEINFO_MIME_TYPE);
$mime  = $finfo->file($file["tmp_name"]); // e.g. "image/jpeg", read from content
$allowed = ["image/jpeg" => "jpg", "image/png" => "png", "image/webp" => "webp"];

if (!isset($allowed[$mime])) {
    exit("Blocked: detected type '$mime' is not an allowed image\n");
}

echo "Accepted a valid " . $mime . " of " . $file["size"] . " bytes.\n";
?>

Accepted a valid image/jpeg of 248173 bytes.

<?php
// 🎯 YOUR TURN — finish the size + error check, then run it.
// $file is a pretend $_FILES entry so this runs anywhere.
$file = ["error" => 0, "size" => 5_000_000, "tmp_name" => "/tmp/x"];

$maxBytes = 2 * 1024 * 1024; // 2 MB

// 1) Reject the upload unless error is exactly UPLOAD_ERR_OK
if ($file["error"] !== ___) {           // 👉 the constant that means "success"
    exit("Upload failed\n");
}

// 2) Reject anything bigger than $maxBytes
if ($file["size"] > ___) {              // 👉 the variable holding the 2 MB cap
    exit("Too big\n");
}

echo "Size check passed\n";

// ✅ Expected output (with size 5,000,000 and a 2 MB cap):
//    Too big
?>

Too big

<?php
// After validation, MOVE the file out of /tmp into permanent, SAFE storage.
$file    = $_FILES["photo"];
$ext     = "jpg";                       // from your validated $allowed map, NOT the user
$finfo   = new finfo(FILEINFO_MIME_TYPE);
$mime    = $finfo->file($file["tmp_name"]);

// Generate a SAFE, unguessable filename. Never reuse the user's name —
// it can contain "../", null bytes, or collide with another upload.
$safeName = bin2hex(random_bytes(16)) . "." . $ext; // e.g. 9f8a...e2.jpg

// Store OUTSIDE the web root so the file can't be requested or executed directly.
$storageDir = "/var/www/storage/uploads"; // NOT inside /public
$dest       = $storageDir . "/" . $safeName;

// move_uploaded_file() is the ONLY safe mover: it confirms the file really came
// from an HTTP upload before moving it. Plain rename()/copy() do not.
if (!move_uploaded_file($file["tmp_name"], $dest)) {
    exit("Could not store the file.\n");
}

echo "Stored as: $safeName\n";
echo "Full path: $dest\n";
?>

Stored as: 9f8a4c1b7d2e6f30a5b8c9d0e1f2a3b4.jpg
Full path: /var/www/storage/uploads/9f8a4c1b7d2e6f30a5b8c9d0e1f2a3b4.jpg

<?php
// 🎯 YOUR TURN — generate a SAFE filename, then run it.
// Never trust the user's original name. Build your own from random bytes
// plus an extension you chose from a whitelist.

$ext = "png"; // came from your validated MIME map, NOT from the user

// 1) 16 random bytes as hex => a 32-char, unguessable, collision-proof name
$random = bin2hex(___);                 // 👉 the function that returns N secure random bytes

// 2) Join the random part and the extension with a dot
$safeName = $random . "." . ___;        // 👉 the variable holding the extension

echo "Looks like: " . (strlen($safeName) === 36 ? "OK" : "WRONG LENGTH") . "\n";

// ✅ Expected output:
//    Looks like: OK
?>

Looks like: OK

<?php
// serve.php?id=9f8a...b4 — files live OUTSIDE the web root, so a PHP controller
// is the gatekeeper. It can check login/ownership BEFORE streaming the bytes.

$id = $_GET["id"] ?? "";

// Allow only the safe charset you generated. This kills path traversal: a value
// like "../../etc/passwd" contains "/" and "." and is rejected outright.
if (!preg_match("/^[a-f0-9]{32}\.(jpg|png|webp)$/", $id)) {
    http_response_code(400);
    exit("Bad file id\n");
}

$path = "/var/www/storage/uploads/" . $id; // safe: $id is already whitelisted
if (!is_file($path)) {
    http_response_code(404);
    exit("Not found\n");
}

// (Here you would check the logged-in user is allowed to see THIS file.)

$finfo = new finfo(FILEINFO_MIME_TYPE);
header("Content-Type: " . $finfo->file($path));
header("Content-Length: " . filesize($path));
readfile($path); // streams the file straight to the browser
?>

<?php
// Flysystem gives every storage backend the SAME API, so swapping local disk
// for S3 is a one-line config change, not a rewrite. No vendor lock-in.
// Install: composer require league/flysystem
require __DIR__ . "/vendor/autoload.php";

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
use League\Flysystem\Visibility;

// --- LOCAL adapter (development) ---
$adapter    = new LocalFilesystemAdapter("/var/www/storage");
$filesystem = new Filesystem($adapter);

// --- The SAME code runs against S3 in production. Only the adapter changes:
//   composer require league/flysystem-aws-s3-v3
//   $adapter    = new AwsS3V3Adapter($s3Client, "myapp-uploads");
//   $filesystem = new Filesystem($adapter);

// write/read/copy/move/delete — identical on every backend.
$filesystem->write("uploads/avatar.jpg", $jpgBytes, [
    "visibility" => Visibility::PUBLIC, // S3 objects default to PRIVATE
]);
$contents = $filesystem->read("uploads/avatar.jpg");
$filesystem->move("uploads/avatar.jpg", "archive/avatar.jpg");
$filesystem->delete("uploads/old-photo.png");

// STREAM big files so a 2 GB upload uses ~8 KB of RAM, not 2 GB:
$stream = fopen("huge.zip", "rb");
$filesystem->writeStream("backups/huge.zip", $stream);
fclose($stream);

echo "Storage backend swapped with one line — app code untouched.\n";
?>