Skip to content
Belikhun edited this page Sep 15, 2026 · 1 revision

📦 Files

Blink stores a file as two separate things: a row describing the upload, and the content, kept under the hash of its own bytes.

That split is what makes two uploads of the same file cost one copy. Each upload still gets its own row, with its own name, uploader and lifetime, and the content only goes when the last row pointing at it does.

Taking a file

use Blink\File;

// From a request.
$file = $request -> requiredFile("avatar") -> store();

// From disk.
$file = File::fromPath("/tmp/report.pdf", "Q3 report.pdf");
$file = File::fromPath($generated, "report.pdf", move: true);

// From what you already have in hand.
$file = File::fromContent($csv, "export.csv");

Each returns a File, which is an ordinary Model: query it, relate to it by id, let the audit log record it.

$file -> id;
$file -> hash;        // sha256 of the content
$file -> filename;    // "Q3 report.pdf"
$file -> extension;   // "pdf"
$file -> mimetype;    // "application/pdf"
$file -> size;
$file -> author;      // the UserBase who uploaded it, when there was one
$file -> created;

The uploader defaults to the signed-in user. Pass one explicitly when the upload belongs to someone else:

File::fromPath($path, $name, $someUser);

Reading it back

$file -> content();     // the whole thing
$file -> stream();      // a read handle; you close it
$file -> path();        // a local path, when the store has one
$file -> exists();      // whether the store still holds the content

content() and stream() throw FileContentMissing when the row is there and the bytes are not. path() returns null for a store that keeps content somewhere other than the local disk, which is why anything serving a file should be ready to stream.

Serving one:

use Blink\Http\Response\FileResponse;
use Blink\Http\Response\PartedFileResponse;

return new FileResponse($file);                    // inline
return new FileResponse($file, download: true);    // as an attachment
return new PartedFileResponse($file);              // honours Range, for media

Uploads

$upload = $request -> requiredFile("avatar");   // throws RequestFileMissing when absent
$upload = $request -> file("avatar");           // or null

$upload -> name;              // "cat.png", as the client sent it
$upload -> extension;         // "png"
$upload -> size;
$upload -> type;              // what the client claimed
$upload -> detectedType();    // what the content actually reads as

store() moves it into the file store. image() does the same after checking it really is an image:

$avatar = $request -> requiredFile("avatar") -> image();

Three things have to hold: the extension is in CONFIG::$IMAGE_ALLOW, the size is within CONFIG::$IMAGE_SIZE, and the content reads as an image. The last one matters, because the extension and the declared type are both the client's word. isImage() asks the same question without throwing.

Dedup, and what deleting means

Two uploads of identical bytes produce two rows and one copy on disk:

$a = File::fromContent("hello", "greeting.txt");   // row 1
$b = File::fromContent("hello", "hello.txt");      // row 2

$a -> hash === $b -> hash;   // true
$a -> shared();              // 2

delete() removes the row, and the content only when nothing else points at it:

$a -> delete();   // row 1 gone, content stays: row 2 still needs it
$b -> delete();   // row 2 gone, content removed

The content goes after the transaction commits. A rollback can put a row back; it cannot put bytes back.

⚠️ Deleting rows in bulk goes around this. DB::table("files") -> where(...) -> delete() leaves the content behind with nothing pointing at it. file:prune is what sweeps that up.

Where content lives

CONFIG::$FILE_STORE names the store. local is built in, and keeps content on disk under CONFIG::$FILES_ROOT, nested under the first characters of its hash:

data/files/7d/95/7d95d9eeb9c191ad25da1c2014f6985c9a3094bf5065029ea0a79767f0522ce6

The nesting is the point. A hash is evenly distributed by construction, so two levels of two hex characters spread content across 65,536 directories without anything having to decide where a file belongs. Everything in one directory turns every lookup into a scan of a directory holding every file the site has ever taken. CONFIG::$FILE_SHARD_DEPTH sets the levels; empty directories are removed as content goes.

Content is addressed by CONFIG::$FILE_HASH, sha256 by default. A hash anyone can construct a collision for would let a crafted upload take the place of an existing file, which is why this is not md5.

⚠️ Changing $FILE_HASH on a site that already holds files leaves them unreachable: their rows carry hashes in the old algorithm.

Another store

Implement Blink\File\Store and register it from a module's attach():

namespace App\Storage;

use Blink\File\Store;

class S3Store implements Store {
	public function name(): string { return "s3"; }

	public function exists(string $hash): bool { ... }
	public function put(string $hash, string $source, bool $move = false): void { ... }
	public function get(string $hash): ?string { ... }
	public function stream(string $hash) { ... }
	public function size(string $hash): int { ... }
	public function path(string $hash): ?string { return null; }
	public function forget(string $hash): bool { ... }
	public function hashes(): iterable { ... }
}
public function attach(): void {
	File::useStore(new S3Store());
}
CONFIG::$FILE_STORE = "s3";

A store deals only in content, addressed by hash. Names, uploaders and timestamps never reach it, which is what lets one store back several sites, or a site move between stores without touching its rows.

path() returns null when there is no local file, and callers fall back to stream(). hashes() is what file:prune walks; a store that cannot enumerate returns nothing and pruning skips it.

From the console

php core/blink file:list
php core/blink file:list --shared
php core/blink file:list --hash=7d95d9ee...
php core/blink file:prune
php core/blink file:prune --orphans --rows --force

file:list shows the newest rows, how many share each piece of content, and whether the store still holds it.

file:prune reconciles the two halves and reports before changing anything:

2 item(s) in the store, 5 row(s) in the table.
1 orphaned item(s), 14 B on disk.
1 row(s) pointing at content that is gone.

--orphans deletes content nothing points at. --rows deletes rows whose content is gone. Neither happens without being asked.

Clone this wiki locally