MinIO Object Storage

01Informasi Dokumen

02Quick Overview

Sebelumnya foto asset disimpan di disk lokal server. Sekarang foto baru diunggah ke bucket MinIO privat. Database hanya menyimpan key object (path relatif di dalam bucket). Saat detail transaksi dibuka, API membuat presigned URL sementara (default 15 menit) dan mengirimkannya di field *_url yang sudah ada, sehingga aplikasi mobile tidak perlu diubah.

03Arsitektur

Mobile/Web ──(base64 / multipart)──► Controller Asset (Asset_c)
                                         │  identitas dari JWT (ResolveContext)
                                         ▼
                                  AssetImageStorage
                                  - validasi gambar (ukuran, MIME, piksel)
                                  - susun key unik
                                  - lacak key baru untuk kompensasi
                                         ▼
                              ObjectStorageService (interface)
                                         ▼
                              S3ObjectStorageService ──► MinIO bucket privat
                                                         (Flysystem + AWS SDK)

Baca:  detail response ─► AssetImageStorage::url() ─► presigned GET URL (offline signing)

Karena client dibuat lazy, konfigurasi MinIO yang kosong tidak mengganggu request non-asset maupun pembacaan data asset lama. Hanya upload baru yang gagal.

Alur file yang dijalankan

A. Saat aplikasi menyala (sekali, tanpa menghubungi MinIO)

flowchart TD
    A[".env<br/>MINIO_* dan NAME_APPLICATION"] --> B["config/object_storage.php<br/>endpoint, bucket, batas, daftar modul"]
    C["bootstrap/app.php<br/>baris 109"] --> D["ObjectStorageServiceProvider"]
    B --> D
    D --> E["ObjectStorageService<br/>S3ObjectStorageService"]
    D --> F["ObjectStorageManager"]
    D --> G["AssetImageStorage"]
    E -. "client S3 baru dibuat saat pertama dipakai" .-> H["MinIO"]

B. Upload file (contoh: ajukan klaim garansi dengan foto tanda terima)

sequenceDiagram
    participant C as Mobile/Web
    participant M as JwtAuth +<br/>ResolveContext
    participant K as Controller<br/>Asset_c
    participant T as TracksObject<br/>Uploads
    participant I as AssetImage<br/>Storage
    participant S as S3Object<br/>StorageService
    participant O as MinIO
    participant D as Model +<br/>database

    C->>M: POST garansi/id/ajukan<br/>(foto base64 atau multipart)
    M->>M: cek JWT, isi ctx.id_company<br/>dan ctx.id_karyawan
    M->>K: request + ctx
    K->>T: uploadAssetImage lalu<br/>uploadTrackedImage
    T->>T: uploadIdentity, validasi<br/>company dan karyawan dari ctx
    T->>I: upload(foto, company,<br/>karyawan, track, submodul)
    I->>I: cek ukuran, MIME asli,<br/>piksel, ekstensi
    I->>S: keyForUpload(company/asset/<br/>submodul/karyawan/hex.ext)
    S-->>I: key lengkap<br/>(awalan NAME_APPLICATION)
    I->>T: track(key), dicatat sebelum upload
    I->>S: uploadStream(key, stream, mime)
    S->>S: filesystem(), baca config<br/>lalu buat client S3<br/>(Flysystem + AWS SDK)
    S->>O: PutObject (bucket privat)
    O-->>S: OK
    I-->>K: key
    K->>D: simpan key di kolom foto<br/>(dalam transaksi)
    K->>T: releaseTrackedObjects (sukses)
    K-->>C: response sukses

C. Ambil file (presigned URL) (contoh: buka detail transaksi)

sequenceDiagram
    participant C as Mobile/Web
    participant K as Controller<br/>Asset_c
    participant D as Model<br/>fotoUrl
    participant I as AssetImage<br/>Storage
    participant S as S3Object<br/>StorageService
    participant O as MinIO

    C->>K: GET detail transaksi
    K->>D: ambil data + key foto<br/>dari database
    D->>I: url(key)
    I->>I: isObjectKey(key)?
    alt key object MinIO
        I->>S: temporaryUrl(key, sekarang + TTL)
        S->>S: tanda tangan offline,<br/>tanpa request ke MinIO
        S-->>I: presigned URL
    else path lokal lama
        I->>I: fallback Uploads_c<br/>(file di disk server)
    end
    I-->>D: URL
    D-->>K: data + field *_url
    K-->>C: response detail
    C->>O: GET presigned URL (langsung ke MinIO)
    O-->>C: file gambar

D. Hapus file (hanya kompensasi saat proses gagal, belum ada endpoint hapus untuk pengguna)

sequenceDiagram
    participant K as Controller<br/>Asset_c
    participant T as TracksObject<br/>Uploads
    participant I as AssetImage<br/>Storage
    participant S as S3Object<br/>StorageService
    participant O as MinIO

    K->>K: upload atau simpan<br/>database gagal (catch)
    K->>T: cleanupAssetObjects lalu<br/>cleanupTrackedObjects
    loop setiap key baru di request ini
        T->>I: deleteNew(key)
        I->>I: isObjectKey(key)?<br/>key lama atau bersama diabaikan
        I->>S: delete(key)
        S->>O: DeleteObject
    end
    T->>T: kosongkan daftar pelacakan

Ringkasan file yang dilewati per langkah:

Untuk fitur baru, alurnya sama. Yang berbeda hanya Controller dan Model milik fitur itu, serta ObjectStorageManager::for('<modul>') yang menggantikan AssetImageStorage sebagai pintu masuk.

04Konfigurasi

Semua nilai dibaca dari .env lewat config/object_storage.php.

Syarat konfigurasi:

• endpoint, access_key, secret_key, bucket, region wajib terisi.
• endpoint harus http/https, punya host, tanpa user/password, query, atau fragment.
• Bucket harus privat; jangan aktifkan public policy.
• Akun layanan hanya butuh izin baca, tulis, dan hapus pada prefix yang dipakai.
• Hostname di URL bertanda tangan tidak boleh diubah (mis. oleh proxy), karena signature akan tidak cocok.
• Simpan kredensial di server/secret manager, jangan di-commit.

Modul didaftarkan di config/object_storage.php pada kunci modules. Menambah fitur baru berarti menambah satu entri di sana, tanpa variabel .env baru:

⚠️ Catatan: API/.env.example saat ini belum memuat variabel MINIO_* dan NAME_APPLICATION. Disarankan menambahkannya (dengan nilai placeholder) agar developer baru tahu variabel apa saja yang dibutuhkan.

05Format Key Object

Key baru dibuat sekali, disimpan ke database apa adanya, lalu dipakai tanpa diubah untuk baca/hapus/signing.

NAME_APPLICATION/id_company/asset/{garansi|perbaikan|disposal}/id_karyawan/<32 hex acak>.<ext>

Contoh sintetis:

• profesional_v3/COMP01/asset/garansi/EMP02/0123456789abcdef0123456789abcdef.png
• profesional_v3/COMP01/asset/perbaikan/EMP02/1123456789abcdef0123456789abcdef.jpg
• profesional_v3/COMP01/asset/disposal/EMP02/2123456789abcdef0123456789abcdef.webp

Aturan:

Identitas company dan karyawan diambil dari JWT → ResolveContext → ctx.id_company dan ctx.id_karyawan. Nilai dari request body tidak dipakai.

06Alur Upload

Dipakai oleh lima endpoint POST yang sudah ada:

Langkah di AssetImageStorage::upload():

1. Validasi identitas pengunggah (company dan karyawan).
2. Baca gambar: UploadedFile (multipart) atau string base64. Base64 harus ketat; data-URI harus bertipe image/jpeg|png|webp dan cocok dengan isi file.
3. Cek ukuran (maks max_bytes) dan tolak file kosong.
4. Cek isi sebenarnya dengan getimagesizefromstring dan finfo; MIME harus JPEG/PNG/WebP, dan lebar × tinggi tidak melebihi max_pixels.
5. Susun key baru (bagian 5).
6. Catat key ke daftar pelacak sebelum upload, lalu uploadStream dengan visibility: private dan ContentType sesuai MIME.

Bila input kosong, gambar lama yang sudah tersimpan dipertahankan. Client tidak bisa mengirim key atau URL yang sudah ada sebagai upload.

07Alur Baca (Presigned URL)

AssetImageStorage::url($path) menentukan perlakuan berdasarkan bentuk key:

Hal yang perlu diketahui:

• URL dibuat offline (tanpa menghubungi MinIO dan tanpa HEAD). Bila object dihapus dari luar, URL tetap terbentuk tetapi client menerima 404.
• Presigned URL adalah bearer capability: siapa pun yang memegangnya bisa mengunduh sampai kedaluwarsa. Jangan dipublikasikan atau dicatat di log.
• Setelah URL kedaluwarsa, client harus memanggil ulang endpoint detail untuk mendapat URL baru. Tidak ada header otorisasi tambahan.
• Key lama tanpa prefix tetap ditandatangani di key aslinya, dan nama aplikasi lama tetap dikenali walau NAME_APPLICATION berubah.

08Konsistensi Data dan Kompensasi

MinIO dan database tidak atomik. Pengamannya:

1. Cek aktor/company/status dilakukan di transaksi preflight yang di-lock, sebelum upload, lalu dicek ulang di transaksi persistensi.
2. Upload tidak pernah dijalankan di dalam closure transaksi yang bisa di-retry.
3. Hanya key yang baru dibuat yang dilacak (termasuk upload yang error di jaringan padahal mungkin sudah diterima server).
4. Bila salah satu upload atau penyimpanan DB gagal, cleanupAssetObjects() menghapus key baru tersebut (best-effort).
5. Setelah commit sukses, pelacakan dilepas sebelum notifikasi dikirim; gagal notifikasi tidak menghapus gambar yang sudah tersimpan.
6. File lama atau yang dipakai bersama tidak pernah dihapus (termasuk snapshot asset_data.foto_dokumen_garansi yang masih legacy).

Risiko tersisa: proses mati mendadak, commit DB yang tidak pasti, atau gagal kompensasi dapat menyisakan object yatim di bucket. Log kompensasi hanya memuat key yang dibuat. Tidak ada purge otomatis maupun worker retry, jadi rekonsiliasi manual (cek referensi di database sebelum menghapus) diperlukan.

09Penanganan Error

Timeout client S3: connect 5 detik, total 30 detik.

10Keamanan

• Bucket privat; objek ditulis dengan visibility: private.
• Tipe file ditentukan dari isi file, bukan dari nama file atau MIME dari client.
• Segmen key divalidasi ketat (anti path traversal); nilai tidak pernah di-trim atau dinormalisasi.
• Kredensial hanya dari environment; log tidak memuat URL bertanda tangan maupun kredensial.
• Akun layanan MinIO sebaiknya dibatasi ke bucket/prefix terkait dengan hak minimal.

11Panduan Operasional

Setup awal (menyiapkan server baru)

1. Pastikan bucket sudah dibuat di MinIO dan berstatus privat.
2. Buat akun layanan khusus dengan izin baca/tulis/hapus pada bucket.
3. Isi variabel MINIO_* dan NAME_APPLICATION di .env server.
4. Pastikan MINIO_ENDPOINT dapat dijangkau dari server API dan dari perangkat client (DNS dan TLS valid).
5. Bila client mengunduh dari browser dan memerlukan CORS, atur CORS di MinIO. ⚠️ Asumsi: aplikasi mobile tidak memerlukannya.
6. Uji manual: kirim satu foto lewat salah satu endpoint, lalu buka URL pada response detail.

Mengganti NAME_APPLICATION: aman. Object lama tetap terbaca di key aslinya; hanya upload baru yang memakai nama baru.

Mengganti endpoint/bucket: bukan migrasi otomatis. Key di database hanya bermakna di bucket yang sama. Memindahkan object atau menulis ulang key harus lewat migrasi terpisah yang disetujui.

Troubleshooting

12Pengujian

tests/Asset/AssetObjectStorageTest.php memakai fake storage, validasi gambar, test controller, dan signing S3 offline sehingga tidak butuh .env, MinIO, atau SQL.

cd API
vendor/bin/phpunit tests/Asset/AssetObjectStorageTest.php

Test modul generik ada di tests/Storage/ObjectStorageManagerTest.php:

cd API
vendor/bin/phpunit tests/Storage tests/Asset/AssetObjectStorageTest.php

Per 9 Oktober 2026, kedua perintah di atas lulus (21 test). Sebelum rilis, perlu diverifikasi manual: koneksi MinIO nyata, kebijakan bucket privat, CORS (bila perlu), serta integrasi end-to-end dengan JWT dan SQL (race pada persistensi). Jangan menjalankan suite integrasi DB yang ada terhadap resource yang belum dikonfirmasi.

13Batasan dan Hal yang Belum Ada

• Yang sudah memakai MinIO baru modul Asset (garansi, perbaikan, disposal). Uploads_c dan modul lain belum disentuh; fitur baru memakai ObjectStorageManager (bagian 15).
• Lapisan generik saat ini hanya untuk gambar (JPEG, PNG, WebP). PDF dan dokumen belum didukung; ObjectStorageService mentah (manager->raw()) bisa dipakai untuk kebutuhan di luar gambar.
• ⚠️ Belum ada pembersihan otomatis object yatim, retry worker, atau migrasi file lokal lama ke MinIO.
• ⚠️ .env.example belum memuat variabel MinIO.
• ⚠️ Belum ada verifikasi koneksi MinIO nyata dalam pengujian otomatis.

14Referensi Kode

15Memakai di Fitur Baru

Panduan ini membangun satu fitur contoh dari nol sampai bisa upload, ambil URL, ganti, dan hapus foto. Fitur fiktifnya bernama Kunjungan (laporan kunjungan dengan satu foto bukti), modul storage kunjungan. Nama tabel, kolom, dan class di bawah adalah contoh sintetis; ganti dengan milik fitur Anda. Fitur baru tidak perlu menyentuh S3, Flysystem, atau kode asset.

15.1 Gambaran: apa yang dibuat

flowchart LR
    A["1. config/object_storage.php<br/>daftarkan modul"] --> B["2. Database<br/>kolom foto VARCHAR 255"]
    B --> C["3. Route<br/>routes/modules/kunjungan"]
    C --> D["4. Model<br/>simpan dan baca key"]
    D --> E["5. Controller<br/>upload, URL, ganti, hapus"]
    E --> F["6. Test"]
    F --> G["7. Uji manual ke MinIO"]

Aturan emas yang dipakai di semua langkah:

15.2 Langkah 1: daftarkan modul

config/object_storage.php, tambah satu entri di modules:

'modules' => [
    'asset' => [ /* sudah ada */ ],
    'kunjungan' => [
        'submodules' => ['bukti'],      // sub-folder yang diizinkan, [] bila tidak perlu
        'max_bytes'  => 3145728,        // opsional: 3 MB, menimpa batas umum (5 MB)
        // 'max_pixels' => 12000000,    // opsional
        // 'ttl' => 600,                // opsional: masa berlaku URL 10 menit
    ],
],

Tidak ada variabel .env baru. Bucket, kredensial, dan NAME_APPLICATION dipakai bersama. Key yang terbentuk:

NAME_APPLICATION/id_company/kunjungan/bukti/id_karyawan/<32 hex>.<ext>

15.3 Langkah 2: database

Kolom penyimpan foto harus muat 255 karakter (batas panjang key). Isinya key lengkap seperti di atas. Karena skema proyek diubah lewat SQL manual, siapkan SQL dan jalankan sendiri (contoh, sesuaikan dengan tabel Anda):

CREATE TABLE kunjungan (
    id            VARCHAR(36)  NOT NULL PRIMARY KEY,
    id_company    VARCHAR(50)  NOT NULL,
    id_karyawan   VARCHAR(50)  NOT NULL,
    catatan       VARCHAR(255) NULL,
    foto_bukti    VARCHAR(255) NULL,      -- key object MinIO, BUKAN URL
    created_at    DATETIME     NOT NULL
);

15.4 Langkah 3: route

Ikuti pola modul lain (routes/modules/asset/): satu folder per modul dengan _config.php dan file route.

routes/modules/kunjungan/_config.php

<?php

return [
    // namespace tidak perlu: controller berada langsung di App\Http\Controllers
    'middleware' => ['jwt.api', 'jwt.ctx'],   // jwt.ctx mengisi ctx.id_company dan ctx.id_karyawan
];

routes/modules/kunjungan/RouteKunjungan.php

<?php

use Laravel\Lumen\Routing\Router;

/** @var Router $router */

// Awalan URL otomatis /kunjungan (nama folder modul), jadi path di bawah relatif terhadap itu.
$router->post('tambah', 'Kunjungan_c@store');                 // POST   /kunjungan/tambah
$router->get('{id}', 'Kunjungan_c@show');                     // GET    /kunjungan/{id}
$router->post('{id}/foto', 'Kunjungan_c@gantiFoto');          // POST   /kunjungan/{id}/foto
$router->delete('{id}', 'Kunjungan_c@destroy');               // DELETE /kunjungan/{id}

Aturan yang dipakai pemuat route proyek (RouteLoader): awalan URL diambil dari nama folder modul, namespace boleh dikosongkan, dan middleware digabung dari routes/modules/_config.php (localization) ditambah milik modul. Modul asset memakai namespace Asset karena controller-nya berada di sub-folder; modul absensi tidak punya _config.php sendiri. ⚠️ Pastikan route muncul pada daftar route dan test route yang menghitung jumlah route (sudah gagal sebelum perubahan ini karena angka 343) diperbarui bila Anda menjaganya.

15.5 Langkah 4: model

app/Models/Kunjungan_m.php. Model hanya menyimpan dan membaca key, tidak tahu apa pun soal MinIO.

<?php

namespace App\Models;

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

class Kunjungan_m
{
    public static function create(string $company, string $karyawan, ?string $catatan, string $fotoKey): object
    {
        $id = (string) Str::uuid();
        DB::transaction(function () use ($id, $company, $karyawan, $catatan, $fotoKey): void {
            DB::table('kunjungan')->insert([
                'id' => $id, 'id_company' => $company, 'id_karyawan' => $karyawan,
                'catatan' => $catatan, 'foto_bukti' => $fotoKey, 'created_at' => now(),
            ]);
        });
        return self::find($company, $id);
    }

    public static function find(string $company, string $id): ?object
    {
        return DB::table('kunjungan')->where('id_company', $company)->where('id', $id)->first();
    }

    public static function updateFoto(string $company, string $id, string $fotoKey): void
    {
        DB::table('kunjungan')->where('id_company', $company)->where('id', $id)->update(['foto_bukti' => $fotoKey]);
    }

    public static function delete(string $company, string $id): void
    {
        DB::table('kunjungan')->where('id_company', $company)->where('id', $id)->delete();
    }
}

15.6 Langkah 5: controller (upload, URL, ganti, hapus)

app/Http/Controllers/Kunjungan_c.php

<?php

namespace App\Http\Controllers;

use App\Libraries\ApiResponse;
use App\Models\Kunjungan_m;
use App\Support\Storage\ModuleImageStorage;
use App\Support\Storage\ObjectStorageConfigurationException;
use App\Support\Storage\ObjectStorageManager;
use App\Traits\TracksObjectUploads;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use InvalidArgumentException;
use Throwable;

class Kunjungan_c extends BaseController
{
    use TracksObjectUploads;

    /** Satu-satunya titik masuk ke storage untuk fitur ini. */
    private function images(): ModuleImageStorage
    {
        return app(ObjectStorageManager::class)->for('kunjungan');
    }

    /** Foto dari multipart (file) atau JSON (base64 / data-URI). */
    private function foto(Request $request)
    {
        return $request->file('foto') ?? $request->input('foto');
    }

    /** Ubah key database menjadi URL sementara untuk response. */
    private function present(object $row): array
    {
        return [
            'id' => $row->id,
            'catatan' => $row->catatan,
            'foto_bukti_url' => $row->foto_bukti ? $this->images()->url($row->foto_bukti) : '',
        ];
    }

    private function failure(Throwable $e, string $log): JsonResponse
    {
        if ($e instanceof InvalidArgumentException) {      // gambar tidak valid, identitas tidak valid
            return ApiResponse::error('BUSINESS_RULE_VIOLATION', $e->getMessage());
        }
        Log::error($log, ['exception' => $e]);
        return ApiResponse::error('SYSTEM_ERROR', $e instanceof ObjectStorageConfigurationException
            ? $e->getMessage() : 'Terjadi kesalahan saat memproses kunjungan.');
    }

    // ---------- UPLOAD: POST kunjungan/tambah ----------
    public function store(Request $request): JsonResponse
    {
        if ($error = $this->validateRequest($request, ['catatan' => 'nullable|string|max:255', 'foto' => 'required'])) {
            return $error;
        }
        $ctx = $request->attributes->get('ctx');
        $images = $this->images();
        try {
            // 1) unggah dulu (di luar transaksi); key baru otomatis dilacak
            $key = $this->uploadTrackedImage($images, $this->foto($request), $request, 'bukti');
            // 2) simpan key ke database
            $row = Kunjungan_m::create((string) $ctx->id_company, (string) $ctx->id_karyawan, $request->input('catatan'), $key);
            // 3) sukses: object baru dipertahankan
            $this->releaseTrackedObjects();
            return ApiResponse::success('CREATED', $this->present($row));
        } catch (Throwable $e) {
            $this->cleanupTrackedObjects($images);        // gagal: hapus object baru yang yatim
            return $this->failure($e, 'Gagal menyimpan kunjungan.');
        }
    }

    // ---------- AMBIL URL: GET kunjungan/{id} ----------
    public function show(Request $request, string $id): JsonResponse
    {
        $ctx = $request->attributes->get('ctx');
        try {
            $row = Kunjungan_m::find((string) $ctx->id_company, $id);
            return $row === null
                ? ApiResponse::error('NOT_FOUND', 'Kunjungan tidak ditemukan.')
                : ApiResponse::success('SUCCESS', $this->present($row));   // URL dibuat di sini, offline
        } catch (Throwable $e) {
            return $this->failure($e, 'Gagal membaca kunjungan.');
        }
    }

    // ---------- GANTI: POST kunjungan/{id}/foto ----------
    public function gantiFoto(Request $request, string $id): JsonResponse
    {
        if ($error = $this->validateRequest($request, ['foto' => 'required'])) {
            return $error;
        }
        $ctx = $request->attributes->get('ctx');
        $images = $this->images();
        try {
            $row = Kunjungan_m::find((string) $ctx->id_company, $id);
            if ($row === null) {
                return ApiResponse::error('NOT_FOUND', 'Kunjungan tidak ditemukan.');
            }
            $key = $this->uploadTrackedImage($images, $this->foto($request), $request, 'bukti');
            Kunjungan_m::updateFoto((string) $ctx->id_company, $id, $key);
            $this->releaseTrackedObjects();
        } catch (Throwable $e) {
            $this->cleanupTrackedObjects($images);
            return $this->failure($e, 'Gagal mengganti foto kunjungan.');
        }
        $this->deleteOld($images, $row->foto_bukti);       // hanya SESUDAH database tersimpan
        return ApiResponse::success('UPDATED', $this->present(Kunjungan_m::find((string) $ctx->id_company, $id)));
    }

    // ---------- HAPUS: DELETE kunjungan/{id} ----------
    public function destroy(Request $request, string $id): JsonResponse
    {
        $ctx = $request->attributes->get('ctx');
        try {
            $row = Kunjungan_m::find((string) $ctx->id_company, $id);
            if ($row === null) {
                return ApiResponse::error('NOT_FOUND', 'Kunjungan tidak ditemukan.');
            }
            Kunjungan_m::delete((string) $ctx->id_company, $id);   // hapus data dulu
        } catch (Throwable $e) {
            return $this->failure($e, 'Gagal menghapus kunjungan.');
        }
        $this->deleteOld($this->images(), $row->foto_bukti);       // lalu hapus object-nya
        return ApiResponse::success('DELETED');
    }

    /** Hapus object lama sesudah commit. Gagal hapus tidak boleh menggagalkan request. */
    private function deleteOld(ModuleImageStorage $images, ?string $key): void
    {
        if ($key === null || $key === '') {
            return;
        }
        try {
            $images->deleteNew($key);      // key milik modul lain atau file lokal otomatis diabaikan
        } catch (Throwable $e) {
            Log::warning('Object kunjungan lama gagal dihapus.', ['key' => $key]);
        }
    }
}

Nama method deleteNew berlaku untuk semua key milik modul itu, baru maupun lama. Key dari modul lain atau path file lokal tidak dikenali sehingga tidak dihapus.

Ringkasan: endpoint → pemanggilan storage:

15.7 Langkah 6: test

Test tidak butuh MinIO. Pasang ObjectStorageManager dengan storage palsu (pola yang sama dengan tests/Asset/AssetObjectStorageTest.php; contoh class palsu InMemoryObjectStorage ada di tests/Storage/ObjectStorageManagerTest.php).

$fake = new InMemoryObjectStorage('app');                       // salin class palsu ke test Anda
$container = new \Illuminate\Container\Container();
\Illuminate\Container\Container::setInstance($container);
$container->instance(ObjectStorageManager::class, new ObjectStorageManager($fake, ['modules' => [
    'kunjungan' => ['submodules' => ['bukti']],
]]));

$controller = new Kunjungan_c();
$request = new \Illuminate\Http\Request(['foto' => self::PNG, 'catatan' => 'uji']);
$request->attributes->set('ctx', (object) ['id_company' => 'COMP', 'id_karyawan' => 'EMP']);

// Model memakai DB: untuk skenario 2 dan 4 gunakan database test atau mock Kunjungan_m.
// yang perlu dibuktikan:
// 1. store sukses  -> $fake->objects berisi 1 key "app/COMP/kunjungan/bukti/EMP/<hex>.png"
// 2. store gagal di database -> $fake->deleted berisi key tersebut, $fake->objects kosong
// 3. gantiFoto sukses -> key lama ada di $fake->deleted, key baru ada di $fake->objects
// 4. gantiFoto gagal di database -> key baru terhapus, key lama TETAP ada
// 5. foto bukan gambar -> response 422 BUSINESS_RULE_VIOLATION dan $fake->objects kosong

Jalankan: vendor/bin/phpunit tests/Storage tests/Kunjungan.

15.8 Langkah 7: uji manual ke MinIO nyata

Header standar proyek: api-key, id-company, id-karyawan, locale (nilai di bawah sintetis).

# upload (multipart)
curl -X POST "$API/kunjungan/tambah" -H "api-key: ..." -H "id-company: COMP01" -H "id-karyawan: EMP02" \
     -F "catatan=uji" -F "foto=@selfie.png"

# ambil URL lalu unduh fotonya
curl "$API/kunjungan/<id>" -H "api-key: ..." -H "id-company: COMP01" -H "id-karyawan: EMP02"
curl -o hasil.png "<foto_bukti_url dari response>"

Periksa di MinIO bahwa object berada di NAME_APPLICATION/COMP01/kunjungan/bukti/EMP02/<hex>.png, URL berhasil diunduh, dan setelah DELETE object tersebut hilang.

15.9 Referensi cepat

Pemetaan exception ke response:

15.10 Kesalahan yang sering terjadi

15.11 Daftar file untuk fitur baru

Yang tidak perlu dibuat atau diubah:

Kasus khusus (jarang): modul yang punya file lama di disk lokal atau key historis berformat sendiri butuh satu kelas turunan ModuleImageStorage seperti app/Support/Asset/AssetImageStorage.php, didaftarkan pada entri modul lewat kunci class. Modul baru tanpa data lama tidak membutuhkannya. Lapisan generik saat ini hanya untuk gambar (JPEG, PNG, WebP); untuk jenis file lain pakai raw().

15.12 Urutan kerja yang disarankan

1. Daftarkan modul di config/object_storage.php.
2. Siapkan dan jalankan SQL kolom foto (VARCHAR(255)).
3. Buat model, lalu controller dan route.
4. Tulis test (upload, gagal, ganti, hapus) dan jalankan.
5. Uji manual satu foto ke MinIO nyata dan cek object terbentuk, terbuka lewat URL, dan hilang setelah dihapus.