README

Pilih Bahasa: [Bahasa Indonesia] | English

Package Laravel reusable untuk memilih penyimpanan Lokal, Amazon S3, atau Bunny CDN melalui satu komponen Livewire.

Package ini tidak menggunakan database. Pengaturan disimpan dalam bentuk envelope JSON terenkripsi di:

storage/app/private/.btekno/filesystem.json

Payload terenkripsi tersebut menggunakan enkripsi bawaan aplikasi Laravel dan APP_KEY.

Persyaratan

PHP 8.2 atau lebih baru
Laravel 11, 12, atau 13
Livewire 3 atau 4

Package ini secara otomatis menginstal adapter S3 Flysystem bawaan Laravel, sehingga Amazon S3 dan API Bunny yang kompatibel dengan S3 dapat bekerja tanpa memerlukan package filesystem tambahan.

Instalasi

Setelah memublikasikan repositori ke Packagist atau repositori Composer lainnya:

composer require btekno/filesystem

Fitur package discovery Laravel akan mendaftarkan service provider secara otomatis.

Tampilkan UI pengaturan di dalam halaman administrasi yang membutuhkan autentikasi:

<livewire:btekno::filesystem />

Layout utama aplikasi harus sudah memuat asset Livewire.

Package ini mendaftarkan komponen menggunakan API namespace Livewire 4 dan secara otomatis beralih (fallback) ke API class alias milik Livewire 3.

Bahasa

Komponen ini sudah mencakup terjemahan bahasa Indonesia dan Inggris. Bahasa Indonesia dijadikan sebagai bawaan (default) package, bahkan ketika locale aplikasi utama berbeda.

Gunakan antarmuka default bahasa Indonesia:

<livewire:btekno::filesystem />

Paksa penggunaan bahasa Inggris untuk satu instans komponen:

<livewire:btekno::filesystem locale="en" />

Atur default seluruh package melalui .env:

BTEKNO_FILESYSTEM_LOCALE=id
BTEKNO_FILESYSTEM_REMEMBER_LOCALE=true

Fitur pemilih bahasa menyimpan locale yang dipilih ke dalam session jika middleware session tersedia. Kode locale yang didukung dikonfigurasi dalam config/btekno/filesystem.php.

Setelah menginstal atau memperbarui package, bersihkan cache discovery dan view:

composer dump-autoload
php artisan optimize:clear

Disk yang Terdaftar

Service provider mendaftarkan nama-nama disk stabil berikut:

btekno-local
btekno-s3
btekno-bunnycdn

Package juga mendaftarkan btekno sebagai alias untuk provider yang sedang aktif.

Secara default, disk stabil yang dipilih akan menjadi nilai filesystems.default pada Laravel. Nilai saat ini dapat diakses melalui:

config('btekno.filesystem.active_provider'); // local, s3, atau bunnycdn

config('btekno.filesystem.active_disk');      // btekno-local, btekno-s3, atau btekno-bunnycdn

config('btekno.filesystem.active_directory'); // string kosong atau direktori dasar yang dikonfigurasi

Untuk aplikasi yang berpotensi berganti provider, simpan path file beserta nama disk stabilnya setiap kali mengunggah berkas:

$disk = config('btekno.filesystem.active_disk');
$path = request()->file('photo')->store('photos', $disk);

// Simpan nilai $disk dan $path ke database.

Proses membaca file lama tetap dilakukan secara eksplisit:

$url = Storage::disk($model->disk)->url($model->path);

Package generik tidak dapat memigrasikan file yang sudah ada atau menebak provider mana yang memiliki path jika disimpan tanpa nama disk.

Direktori Dasar (Base Directory)

Setiap provider memiliki opsi bidang (field) direktori dasar. Gunakan nilai relatif seperti:

my-app/media

Package akan menerapkan nilai tersebut sebagai root disk. Kode pada aplikasi dapat tetap menggunakan path relatif biasa:

Storage::disk('btekno')->put('avatars/user-1.jpg', $contents);

Dengan konfigurasi my-app/media, file atau objek fisik akan disimpan pada:

my-app/media/avatars/user-1.jpg

Untuk penyimpanan Lokal, path lengkapnya menjadi storage/app/public/my-app/media/avatars/user-1.jpg. Untuk S3 dan Bunny CDN, key dibuat di bawah bucket atau direktori Storage Zone yang dipilih. URL yang dihasilkan juga mencakup awalan (prefix) tersebut.

Field ini menerima karakter huruf, angka, titik, garis bawah (underscore), tanda hubung (hyphen), dan garis miring (slash). Garis miring di awal dan akhir akan dihapus secara otomatis, serta garis miring berulang akan digabungkan. Package menolak segmen path . dan ... Mengosongkan field ini akan mempertahankan posisi disk pada root aslinya.

Perubahan direktori dasar hanya berpengaruh pada operasi filesystem baru. Data file lama tetap menyimpan path relatif aslinya. Pertahankan informasi disk dan direktori lama jika aplikasi harus tetap menyajikan file dari lokasi sebelumnya.

Penyimpanan Lokal (Local Storage)

Penyimpanan lokal menggunakan direktori storage/app/public. Jalankan perintah ini satu kali pada aplikasi utama:

php artisan storage:link

Bunny CDN

Buat Bunny Storage Zone dengan mengaktifkan kompatibilitas S3 (S3 compatibility). Pada komponen Livewire, masukkan:

Storage Zone name
Storage Zone password
Bunny S3 endpoint, contohnya https://sg-s3.storage.bunnycdn.com
Pull Zone URL, contohnya https://example.b-cdn.net
Storage Zone directory (opsional), contohnya my-app/media

Package menggunakan metode pengalamatan S3 path-style. Nama Storage Zone berfungsi sekaligus sebagai access key dan bucket name.

Keamanan

Komponen secara default membutuhkan pengguna yang telah terautentikasi. Tempatkan komponen ini pada rute yang khusus diakses oleh admin.

Untuk menggunakan Laravel Gate, atur:

BTEKNO_FILESYSTEM_GATE=manage-filesystem-settings

Guard autentikasi non-default dapat dipilih tanpa perlu memublikasikan konfigurasi package:

BTEKNO_FILESYSTEM_GUARD=admin

Gate akan diperiksa saat render awal dan pada setiap aksi (action) Livewire.

Hanya nonaktifkan pemeriksaan autentikasi bawaan jika rute host sudah memiliki perlindungan yang setara:

BTEKNO_FILESYSTEM_REQUIRE_AUTH=false

Direktori pengaturan dibuat dengan hak akses (permission) 0700. Berkas pengaturan dan lock file menggunakan mode 0600 jika didukung oleh sistem operasi. Kredensial tidak pernah di-hydrate kembali ke dalam kolom kata sandi.

⚠️ Penting: Jangan meng-commit file pengaturan terenkripsi ke version control. Meskipun isinya terenkripsi, berkas tersebut terikat pada lingkungan deployment masing-masing.

Perilaku Runtime (Runtime Behavior)

Package membaca dan menerapkan pengaturan terenkripsi saat proses pendaftaran service provider. Tidak diperlukan perubahan pada AppServiceProvider atau config/filesystems.php milik aplikasi host.

Menyimpan pengaturan melalui Livewire akan menyegarkan (refresh) filesystem manager dalam proses PHP saat ini. Proses berjalan lama seperti Queue worker, Octane worker, atau proses persisten lainnya harus di-restart setelah terjadi perubahan provider.

php artisan queue:restart

Gunakan perintah reload yang sesuai jika menggunakan Laravel Octane.

Publikasi Opsional

Package ini dapat langsung berjalan tanpa perlu memublikasikan berkas. Jika ingin melakukan kustomisasi:

php artisan vendor:publish --tag=btekno-filesystem-config
php artisan vendor:publish --tag=btekno-filesystem-views
php artisan vendor:publish --tag=btekno-filesystem-translations

File konfigurasi akan dipublikasikan ke:

config/btekno/filesystem.php

Laravel mengeksposnya melalui config('btekno.filesystem.*').

Pengujian (Test)

composer install
composer test

btekno / filesystem

Maintainers

Package info

Statistics

Security