Skip to main content

​
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.
UtilitasKegunaanInstalasi macOSInstalasi Ubuntu/Debian
GhostscriptMesin inti untuk rendering PDFbrew install ghostscriptsudo apt-get install ghostscript
PopplerMenyediakan pdfinfo untuk membaca metadatabrew install popplersudo apt-get install poppler-utils
pdftkPDF Toolkit untuk proses stempel yang andalbrew install pdftk-javasudo 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: 
php artisan pdf:thumbnail [opsi]
Opsi:
OpsiDeskripsi
--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: 
# 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: 
php artisan documents:generate-thumbnails [opsi]
Opsi:
OpsiDeskripsi
--id=Hanya memproses satu dokumen berdasarkan ID spesifiknya (_id untuk MongoDB).
--forceMemaksa pembuatan ulang thumbnail bahkan untuk dokumen yang sudah memilikinya.
--unprocessed-onlyHanya 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: 
# 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: 
php artisan pdf:stamp [opsi]
Opsi:
GrupOpsiDeskripsi
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: 
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:
OpsiDeskripsi
--id=Hanya memproses satu dokumen berdasarkan ID spesifiknya.
--forceMemproses dokumen meskipun sudah pernah diberi stempel (stamped_at tidak null).
--unprocessed-onlyHanya 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: 
# 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"