Laravel File Storage: Memilih Disk, Visibility, dan Temporary URL

Sebuah file yang diunggah pengguna belum selesai hanya karena sudah masuk ke server. Aplikasi masih perlu menentukan file itu disimpan di disk mana, path apa yang dicatat, bagaimana file diambil kembali, dan siapa yang boleh mengaksesnya.

Di Laravel, keputusan tersebut dapat ditelusuri sebagai satu alur: konteks request yang sudah divalidasi → disk → path file → retrieval atau download → URL sesuai visibility → temporary URL bila aksesnya hanya diperlukan untuk waktu terbatas. Kunci pentingnya adalah membedakan path, URL, visibility, dan authorization. Keempatnya saling berhubungan, tetapi bukan hal yang sama.

Artikel ini mengikuti dokumentasi Laravel 13.x yang diakses pada 4 Oktober 2026 WITA. Contoh kode bersifat dokumentasi-guided dan belum dijalankan. Detail disk, driver, dan konfigurasi proyek harus diperiksa kembali terhadap versi Laravel serta lingkungan penyimpanan yang benar-benar digunakan.

Mulai dari keputusan disk, bukan dari URL

Laravel menyediakan abstraksi filesystem melalui facade Storage. Sebuah disk mewakili driver dan lokasi penyimpanan tertentu. Konfigurasinya berada di config/filesystems.php; aplikasi dapat memiliki beberapa disk, bahkan beberapa disk dengan driver yang sama.

Untuk alur sederhana, bayangkan aplikasi menyimpan dokumen milik pengguna. File tersebut tidak otomatis menjadi “file publik” hanya karena berasal dari request. Pertanyaan pertamanya adalah:

• Apakah file memang boleh diakses tanpa pembatasan aplikasi?
• Apakah aplikasi hanya perlu mengambilnya kembali dari server?
• Apakah file akan disajikan melalui URL yang berlaku sebentar?
• Apakah disk lokal cukup, atau aplikasi membutuhkan disk lain yang konfigurasi dan operasionalnya harus divalidasi terpisah?

Pada driver local, dokumentasi Laravel 13.x menyatakan bahwa operasi file relatif terhadap root disk. Default local yang didokumentasikan mengarah ke storage/app/private. Disk public secara default menggunakan storage/app/public dan ditujukan untuk file yang dapat diakses publik. Ini adalah default dokumentasi, bukan alasan untuk menyalin konfigurasi tersebut ke semua aplikasi tanpa pemeriksaan.

Simpan path yang dikembalikan, bukan menebak lokasi file

Dalam alur upload, method store pada objek file yang sudah tersedia dari request dapat menyimpan file ke direktori dan mengembalikan path-nya. Laravel juga menyediakan Storage::putFile untuk operasi yang sepadan. Contoh minimal berikut hanya menunjukkan hubungan antara file, disk, dan path; ia bukan tutorial route, controller, atau validasi lengkap.

Contoh konseptual, belum dieksekusi:

use Illuminate\Http\Request;

public function store(Request $request): string
{
    // Validasi request dan otorisasi akses adalah prasyarat aplikasi.
    $path = $request->file('document')->store(
        'documents',
        'local'
    );

    // Simpan $path bersama record aplikasi yang relevan.
    return $path;
}

store dapat menghasilkan nama file yang unik dan mengembalikan path, sehingga aplikasi tidak perlu mengarang nama fisik atau mengasumsikan struktur direktori di luar root disk. Jika disk tidak disebutkan, method tersebut menggunakan default disk aplikasi. Jika file harus berada di disk tertentu, nama disk diberikan secara eksplisit seperti pada contoh.

Path ini adalah identitas lokasi relatif terhadap disk. Path bukan URL publik dan bukan keputusan authorization. Record aplikasi dapat menyimpan path tersebut, lalu pada saat pembacaan aplikasi memilih cara akses yang sesuai dengan konteks pengguna dan kebijakan aplikasinya.

Bedakan path, URL, visibility, dan authorization

Empat istilah berikut sering tertukar:

1. Path adalah lokasi file menurut disk, misalnya documents/abc123.pdf.
2. URL adalah alamat yang dapat dipakai klien untuk meminta file, jika disk dan konfigurasinya mendukung cara tersebut.
3. Visibility adalah abstraksi Laravel/Flysystem untuk menandai file sebagai public atau private pada platform penyimpanan.
4. Authorization adalah keputusan aplikasi tentang apakah pengguna tertentu boleh melakukan operasi tertentu terhadap record atau file.

Laravel mendokumentasikan public sebagai indikasi bahwa file pada umumnya dapat diakses oleh pihak lain. Itu tidak sama dengan pemeriksaan bahwa pengguna yang sedang login memiliki hak atas record tertentu. Sebaliknya, private juga bukan pengganti seluruh desain authorization aplikasi.

Karena itu, jangan menulis logika seperti “path diawali folder pengguna, berarti pengguna pasti boleh membacanya”. Ambil record aplikasinya, lakukan pemeriksaan authorization sesuai kebutuhan proyek, lalu pilih operasi storage yang sesuai. Artikel ini tidak mengajarkan policy atau gate; batas itu tetap berada pada lapisan aplikasi dan dibahas terpisah.

Pilih retrieval sesuai kebutuhan pembaca

Jika server perlu membaca isi file, Storage::get mengambil isi sebagai string. Jika tujuan utamanya adalah memaksa browser mengunduh file, Storage::download menghasilkan response download dan dapat menerima nama file serta header tambahan.

use Illuminate\Support\Facades\Storage;

$contents = Storage::disk('local')->get($path);

return Storage::disk('local')->download(
    $path,
    'dokumen.pdf'
);

Fragmen tersebut tidak menyelesaikan authorization. Ia hanya menunjukkan dua bentuk retrieval yang didokumentasikan. Dalam aplikasi nyata, keputusan untuk mengembalikan response harus terjadi setelah konteks record dan hak aksesnya diperiksa.

Jika yang dibutuhkan memang URL, Storage::url($path) dapat menghasilkan URL untuk file pada disk yang mendukungnya. Untuk driver local, dokumentasi menjelaskan bahwa URL biasanya menambahkan /storage pada path. Agar file pada disk public dapat diakses melalui web, Laravel mendokumentasikan symbolic link dari storage/app/public ke public/storage, yang dapat dibuat dengan php artisan storage:link.

URL yang dihasilkan tetap bergantung pada konfigurasi disk dan lingkungan aplikasi. Jangan membentuk URL dengan menggabungkan domain secara manual, dan jangan menganggap bahwa semua disk menghasilkan URL publik dengan perilaku yang sama.

Kapan memakai public, private, atau temporary access?

Gunakan aturan keputusan berikut sebagai titik awal, bukan sebagai pengganti pemeriksaan proyek:

• Public: file memang dirancang untuk dapat diminta tanpa pembatasan per pengguna, misalnya aset yang benar-benar bersifat publik. Pastikan konsekuensi visibility tersebut memang diinginkan.
• Private: file memiliki konteks pengguna, organisasi, atau record tertentu sehingga aplikasi perlu memutuskan akses sebelum mengembalikannya.
• Temporary access: file biasanya tidak perlu menjadi URL publik permanen, tetapi klien atau penerima membutuhkan akses untuk jangka waktu tertentu.

Temporary access bukan berarti “pengguna otomatis berwenang”. Aplikasi tetap perlu memutuskan siapa yang menerima URL dan dalam konteks apa URL itu dibuat. Masa berlaku membatasi waktu berlaku URL sesuai mekanisme disk; ia tidak menjelaskan seluruh kebijakan kepemilikan record, audit, penghapusan, atau perlindungan data aplikasi.

Temporary URL untuk akses yang dibatasi waktu

Laravel mendokumentasikan method temporaryUrl untuk file pada driver local dan s3. Method tersebut menerima path dan waktu kedaluwarsa. Contoh berikut mengikuti bentuk yang ditunjukkan pada dokumentasi Laravel 13.x:

use Illuminate\Support\Facades\Storage;

$url = Storage::disk('local')->temporaryUrl(
    $path,
    now()->plus(minutes: 5)
);

Perhatikan apa yang dilakukan contoh itu dan apa yang tidak dilakukan. Ia meminta disk membuat URL sementara untuk path tertentu dan waktu kedaluwarsa tertentu. Ia tidak memilih penerima URL, tidak memeriksa kepemilikan record, dan tidak membuktikan bahwa konfigurasi proyek sudah benar.

Pada disk local, dokumentasi saat ini juga menjelaskan opsi serve untuk mengaktifkan temporary URL lokal pada konfigurasi disk bila diperlukan, terutama pada aplikasi yang mulai dikembangkan sebelum dukungan tersebut tersedia. Jangan menyalin opsi itu secara buta; cocokkan dengan konfigurasi Laravel dan kebutuhan aplikasi Anda.

Bila proyek menggunakan disk S3 atau layanan yang kompatibel dengan S3, detail kredensial, endpoint, driver, dan perilaku URL harus diperiksa dari konfigurasi serta dokumentasi provider yang digunakan. Dokumentasi Laravel cukup untuk menjelaskan permukaan API framework, bukan untuk menjamin ketersediaan, biaya, latency, atau perilaku semua provider.

Satu alur pemeriksaan sebelum file disajikan

Untuk satu dokumen milik pengguna, alurnya dapat diringkas seperti ini:

1. Request context: file sudah melewati prasyarat validasi yang relevan. Validasi bukan fokus artikel ini, dan aturan yang tepat bergantung pada kebutuhan aplikasi.
2. Authorization: aplikasi memeriksa apakah aktor boleh melakukan operasi terhadap record/file tersebut. URL atau path tidak menggantikan langkah ini.
3. Disk: aplikasi memilih disk yang sesuai, bukan sekadar disk default karena paling mudah dipanggil.
4. Storage path: aplikasi menyimpan path yang dikembalikan dan mengaitkannya dengan record yang tepat.
5. Operation: aplikasi memilih get, download, url, atau temporaryUrl sesuai kebutuhan.
6. Visibility dan masa berlaku: bila file publik, pastikan public memang keputusan yang disengaja; bila sementara, tetapkan waktu kedaluwarsa dan konteks penerimanya.

Alur ini membantu memisahkan bug konfigurasi dari bug kebijakan. Jika file tidak ditemukan, periksa disk dan path. Jika URL salah, periksa konfigurasi URL atau symbolic link. Jika pengguna yang salah dapat mengakses file, masalahnya bukan sekadar path: periksa authorization dan keputusan visibility.

Batas contoh dan hal yang perlu diuji sendiri

Contoh di artikel ini tidak menguji upload, symbolic link, disk lokal, object storage, temporary URL, authorization, atau response download pada aplikasi nyata. Tidak ada klaim bahwa contoh tersebut siap produksi, aman untuk semua jenis file, atau sesuai dengan semua provider.

Sebelum perubahan dibawa ke lingkungan yang lebih penting, cocokkan versi Laravel dan dependency filesystem pada proyek, periksa config/filesystems.php, jalankan contoh pada proyek yang benar-benar digunakan, dan tambahkan pengujian yang sesuai untuk skenario berhasil serta gagal. Jika file menyangkut data yang sensitif, kebutuhan scanning, retention, privasi, atau audit memerlukan keputusan dan bukti khusus di luar cakupan artikel ini.

Aturan praktisnya: simpan path sebagai referensi storage, pilih disk berdasarkan kebutuhan lifecycle, perlakukan visibility sebagai keputusan akses umum, dan lakukan authorization di lapisan aplikasi. Gunakan URL biasa hanya ketika file memang publik; gunakan temporary URL ketika akses terbatas waktu benar-benar sesuai dengan desain aplikasi.