Deduplication & integrity

With deduplicate enabled, identical bytes on the same (disk, visibility) are stored once and shared by reference — and attach() and a same-disk copy() share an original the same way. A reference count on the stored file keeps sharing safe: a physical original is removed — by a delete, a cross-disk move or a replace — only when no other row, soft-deleted rows included, still points at the same file (disk + path), so a soft delete followed by a restore stays lossless even while the file is shared:

// Identical bytes on the same (disk, visibility) are stored once.
$a = MediaLibrary::for($userA)->add($path)->toBucket('docs');   // the source path is only read
$b = MediaLibrary::for($userB)->add($path)->toBucket('docs'); // same bytes -> shared storage

// Deleting $a keeps the file alive while $b still references it.
MediaLibrary::delete($a); // the original stays until the last reference is gone

$b->verifyIntegrity();    // bool — false on drift or a missing file

A content checksum (sha256 by default) backs dedup and optional read-time integrity verification — set verify_checksum_on_read to re-hash the original on stream/download and throw ChecksumMismatch on drift. Variants are never shared: each media generates its own. A still-shared original is never overwritten either — replacing one sharer writes its new bytes to a path of its own — and directories are only tidied away once nothing another row points at is left in them.