> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mejik.web.id/llms.txt
> Use this file to discover all available pages before exploring further.

# PDF Thumbnail & Watermark Commands ( Bahasa Indonesia )

> Ekstraksi halaman pdf untuk thumbnail & pembubuhan watermark pada dokumen pdf

## Dokumentasi Perintah Artisan untuk Pemrosesan PDF

Dokumen ini menjelaskan penggunaan perintah Artisan kustom untuk menghasilkan thumbnail PDF dan menerapkan stempel atau tanda air (watermark) pada dokumen PDF.

### Prasyarat Sistem

Sebelum menggunakan perintah-perintah ini, pastikan utilitas baris perintah berikut telah terinstal di server atau mesin pengembangan lokal Anda.

| Utilitas        | Kegunaan                                     | Instalasi macOS            | Instalasi Ubuntu/Debian              |
| :-------------- | :------------------------------------------- | :------------------------- | :----------------------------------- |
| **Ghostscript** | Mesin inti untuk rendering PDF               | `brew install ghostscript` | `sudo apt-get install ghostscript`   |
| **Poppler**     | Menyediakan `pdfinfo` untuk membaca metadata | `brew install poppler`     | `sudo apt-get install poppler-utils` |
| **pdftk**       | PDF Toolkit untuk proses stempel yang andal  | `brew install pdftk-java`  | `sudo apt-get install pdftk`         |

***

## 1. Pembuatan Thumbnail PDF

Fitur ini digunakan untuk membuat pratinjau gambar dari halaman tertentu sebuah file PDF.

### Perintah Inti: `pdf:thumbnail`

Ini adalah perintah level rendah yang melakukan konversi satu PDF menjadi sebuah thumbnail.

**Penggunaan:**

```bash theme={null}
php artisan pdf:thumbnail [opsi]
```

**Opsi:**

| Opsi       | Deskripsi                                                                                     |
| :--------- | :-------------------------------------------------------------------------------------------- |
| `--in=`    | Path atau URL ke file `.pdf` input. **(Wajib)**                                               |
| `--out=`   | Path untuk menyimpan gambar thumbnail (misalnya, `public/thumbnails/my-doc.jpg`). **(Wajib)** |
| `--page=`  | Nomor halaman yang akan dijadikan thumbnail. (Default: `1`)                                   |
| `--width=` | Lebar thumbnail dalam piksel. Tinggi akan disesuaikan secara otomatis. (Default: `400`)       |

**Contoh:**

```bash theme={null}
# Membuat thumbnail selebar 600px dari halaman ke-2 sebuah PDF lokal
php artisan pdf:thumbnail \
--in="storage/app/documents/laporan.pdf" \
--out="public/thumbnails/pratinjau_laporan.jpg" \
--page=2 \
--width=600
```

### Perintah Massal: `documents:generate-thumbnails`

Ini adalah perintah level tinggi yang mencari dokumen di database yang belum memiliki thumbnail dan membuatnya untuk setiap dokumen.

**Penggunaan:**

```bash theme={null}
php artisan documents:generate-thumbnails [opsi]
```

**Opsi:**

| Opsi                 | Deskripsi                                                                                                                                         |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--id=`              | Hanya memproses satu dokumen berdasarkan ID spesifiknya (`_id` untuk MongoDB).                                                                    |
| `--force`            | Memaksa pembuatan ulang thumbnail bahkan untuk dokumen yang sudah memilikinya.                                                                    |
| `--unprocessed-only` | Hanya memproses dokumen di mana field `ThumbnailUrl` bernilai `null` atau kosong. (Ini adalah perilaku default jika tidak menggunakan `--force`). |
| `--width=`           | Lebar thumbnail yang dihasilkan dalam piksel. (Default: `400`)                                                                                    |

**Contoh:**

```bash theme={null}
# Memproses semua dokumen yang membutuhkan thumbnail
php artisan documents:generate-thumbnails --unprocessed-only

# Membuat thumbnail hanya untuk dokumen dengan ID tertentu
php artisan documents:generate-thumbnails --id=5f11895c7dfdb46efb0d3022

# Memaksa pembuatan ulang semua thumbnail dengan lebar 300px
php artisan documents:generate-thumbnails --force --width=300
```

***

## 2. Stempel & Tanda Air (Watermark) PDF

Fitur ini digunakan untuk menerapkan stempel kode QR dan/atau tanda air teks pada dokumen PDF. Hasil akhirnya disimpan sebagai file baru, dan URL-nya disimpan di field `StampedFileUrl` pada model dokumen, tanpa mengubah file asli.

### Perintah Inti: `pdf:stamp`

Ini adalah perintah level rendah yang melakukan operasi stempel/watermark pada satu PDF.

**Penggunaan:**

```bash theme={null}
php artisan pdf:stamp [opsi]
```

**Opsi:**

| Grup           | Opsi                     | Deskripsi                                                                                                   |
| :------------- | :----------------------- | :---------------------------------------------------------------------------------------------------------- |
| **I/O**        | `--in=`                  | Path atau URL ke file `.pdf` input. **(Wajib)**                                                             |
|                | `--out=`                 | Path untuk file `.pdf` hasil stempel. **(Wajib)**                                                           |
|                | `--disk=`                | (Opsional) Laravel filesystem disk untuk menyimpan output (misalnya, `minio`, `s3`).                        |
| **Stempel QR** | `--stamp-qr-string=`     | Teks atau data untuk di-encode dalam kode QR.                                                               |
|                | `--stamp-pages=`         | Halaman untuk diberi stempel (misalnya, `first`, `last`, `all`, `1,3,5`). (Default: `all`)                  |
|                | `--stamp-position=`      | Posisi: `top-left`, `top-right`, `bottom-left`, `bottom-right`. (Default: `top-right`)                      |
|                | `--stamp-size=`          | Lebar dan tinggi kode QR dalam milimeter. (Default: `20`)                                                   |
|                | `--stamp-offset-x=`      | Jarak horizontal dari tepi halaman dalam mm. (Default: `10`)                                                |
|                | `--stamp-offset-y=`      | Jarak vertikal dari tepi halaman dalam mm. (Default: `10`)                                                  |
| **Watermark**  | `--watermark-text=`      | Teks yang akan digunakan sebagai tanda air.                                                                 |
|                | `--watermark-pages=`     | Halaman untuk diberi tanda air. Formatnya sama seperti `--stamp-pages`. (Default: `all`)                    |
|                | `--watermark-position=`  | Posisi tanda air. (Default: `center`)                                                                       |
|                | `--watermark-rotation=`  | Sudut rotasi dalam derajat. (Default: `45`)                                                                 |
|                | `--watermark-color=`     | Warna RGB dalam format string terpisah koma (misalnya, `"255,0,0"` untuk merah). (Default: `"128,128,128"`) |
|                | `--watermark-font-size=` | Ukuran font dalam satuan point. (Default: `48`)                                                             |
|                | `--watermark-opacity=`   | Opasitas dari `0.0` (transparan) hingga `1.0` (solid). (Default: `0.3`)                                     |

**Catatan Penting:** Perintah ini memerlukan file font di `public/fonts/Calibri/Calibri.ttf` untuk me-render watermark.

### Perintah Massal: `documents:generate-stamp`

Ini adalah perintah level tinggi yang memproses dokumen dari database, menerapkan stempel/watermark yang ditentukan, dan mencatat setiap operasi.

**Penggunaan:**

```bash theme={null}
php artisan documents:generate-stamp [opsi]
```

**Fitur Utama:**

* **Opsi Terusan:** Untuk menggunakan opsi-opsi detail dari `pdf:stamp` (seperti `--stamp-position` atau `--watermark-color`), Anda **harus** menggunakan flag `-O`.
* **Placeholder:** Opsi `--stamp-qr-string` dan `--watermark-text` mendukung placeholder dinamis yang akan diganti dengan data dari dokumen yang sedang diproses. Placeholder yang didukung: `{id}` (atau `_id`) dan `{FCallCode}`.
* **Pencatatan (Logging):** Setiap operasi (baik sukses maupun gagal) dicatat dalam koleksi `stamp_logs` di MongoDB.
* **Debugging:** Jalankan perintah dengan flag `-v` untuk melihat output detail secara real-time dari perintah `pdf:stamp`.

**Opsi:**

| Opsi                 | Deskripsi                                                                            |
| :------------------- | :----------------------------------------------------------------------------------- |
| `--id=`              | Hanya memproses satu dokumen berdasarkan ID spesifiknya.                             |
| `--force`            | Memproses dokumen meskipun sudah pernah diberi stempel (`stamped_at` tidak null).    |
| `--unprocessed-only` | Hanya memproses dokumen di mana `stamped_at` bernilai `null`. (Perilaku default)     |
| `--stamp-qr-string=` | String untuk kode QR, mendukung placeholder.                                         |
| `--watermark-text=`  | String untuk watermark, mendukung placeholder.                                       |
| `-O=`                | Meneruskan opsi detail ke perintah `pdf:stamp`. (misalnya, `-O="stamp-pages=first"`) |

**Contoh:**

```bash theme={null}
# Memberi stempel QR dengan FCallCode dokumen di halaman pertama untuk semua dokumen yang belum diproses
php artisan documents:generate-stamp --unprocessed-only \
--stamp-qr-string="{FCallCode}" \
-O="stamp-pages=first"

# Memberi watermark "CONFIDENTIAL" berwarna merah di tengah setiap halaman untuk satu dokumen
php artisan documents:generate-stamp --id=5f11895c7dfdb46efb0d3022 \
--watermark-text="CONFIDENTIAL" \
-O="watermark-color=255,0,0" \
-O="watermark-position=center" \
-O="watermark-pages=all"

# Menggabungkan stempel dan watermark dalam satu eksekusi dengan output verbose untuk debugging
php artisan documents:generate-stamp -v --id=5f11895c7dfdb46efb0d3022 \
--stamp-qr-string="ID: {id}" \
--watermark-text="DRAFT" \
-O="stamp-position=bottom-left" \
-O="watermark-rotation=30" \
-O="watermark-opacity=0.1"
```