Skip to main content

​
PDF Processing Artisan Commands Documentation

This document outlines the usage of custom Artisan commands for generating PDF thumbnails and applying stamps or watermarks to PDF documents.

​
System Prerequisites

Before using any of these commands, ensure the following command-line utilities are installed on your server or local development machine.
UtilityPurposemacOS InstallationUbuntu/Debian Installation
GhostscriptCore PDF rendering enginebrew install ghostscriptsudo apt-get install ghostscript
PopplerProvides pdfinfo for fast metadata readingbrew install popplersudo apt-get install poppler-utils
pdftkThe PDF Toolkit for robust stampingbrew install pdftk-javasudo apt-get install pdftk

​
1. PDF Thumbnail Generation

This feature is used to create an image preview from a specific page of a PDF file.

​
Core Command: pdf:thumbnail

This is the low-level worker command that performs the conversion of a single PDF to a thumbnail. Usage: 
php artisan pdf:thumbnail [options]
Options:
OptionDescription
--in=The path or URL to the input .pdf file. (Required)
--out=The path for the output thumbnail image (e.g., public/thumbnails/my-doc.jpg). (Required)
--page=The page number to create a thumbnail from. (Default: 1)
--width=The width of the final thumbnail in pixels. Height is scaled automatically. (Default: 400)
Example: 
# Create a 600px wide thumbnail from the 2nd page of a local PDF
php artisan pdf:thumbnail \
  --in="storage/app/documents/report.pdf" \
  --out="public/thumbnails/report_preview.jpg" \
  --page=2 \
  --width=600

​
Batch Command: documents:generate-thumbnails

This is the high-level orchestrator command that finds documents in the database that are missing a thumbnail and generates one for each. Usage: 
php artisan documents:generate-thumbnails [options]
Options:
OptionDescription
--id=Process only a single document by its specific ID (or _id for MongoDB).
--forceForce regeneration of thumbnails even for documents that already have one.
--unprocessed-onlyProcess only documents where the ThumbnailUrl field is null or empty. (This is the default
behavior if not using --force).
--width=The width of the generated thumbnails in pixels. (Default: 400)
Examples: 
# Process all documents that need a thumbnail
php artisan documents:generate-thumbnails --unprocessed-only

# Generate a thumbnail only for the document with a specific ID
php artisan documents:generate-thumbnails --id=5f11895c7dfdb46efb0d3022

# Forcefully regenerate all thumbnails in the system as 300px wide images
php artisan documents:generate-thumbnails --force --width=300

​
2. PDF Stamping & Watermarking

This feature is used to apply QR code stamps and/or text watermarks to PDF documents. The final result is saved as a new file, and its URL is stored in the StampedFileUrl field of the document model, leaving the original file untouched.

​
Core Command: pdf:stamp

This is the low-level worker command that performs the stamping/watermarking operation on a single PDF. Usage: 
php artisan pdf:stamp [options]
Options:
GroupOptionDescription
I/O--in=Path or URL to the input .pdf file. (Required)
--out=Path for the output stamped .pdf file. (Required)
--disk=(Optional) The Laravel filesystem disk to save the output to (e.g., minio, s3).
QR Stamp--stamp-qr-string=The text or data to encode in the QR code.
--stamp-pages=Pages to apply the stamp to (e.g., first, last, all, 1,3,5). (Default: all)
--stamp-position=Position: top-left, top-right, bottom-left, bottom-right. (Default: top-right)
--stamp-size=The width and height of the QR code in millimeters. (Default: 20)
--stamp-offset-x=Horizontal margin from the page edge in mm. (Default: 10)
--stamp-offset-y=Vertical margin from the page edge in mm. (Default: 10)
Watermark--watermark-text=The text to use for the watermark.
--watermark-pages=Pages to apply the watermark to. Same format as --stamp-pages. (Default: all)
--watermark-position=Position of the watermark. (Default: center)
--watermark-rotation=Rotation angle in degrees. (Default: 45)
--watermark-color=RGB color as a comma-separated string (e.g., "255,0,0" for red). (Default: "128,128,128")
--watermark-font-size=Font size in points. (Default: 48)
--watermark-opacity=Opacity from 0.0 (transparent) to 1.0 (opaque). (Default: 0.3)
Important Note: This command requires a font file located at public/fonts/Calibri/Calibri.ttf for rendering watermarks.

​
Batch Command: documents:generate-stamp

This is the high-level orchestrator command that processes documents from the database, applies the specified stamps/watermarks, and logs the operation. Usage: 
php artisan documents:generate-stamp [options]
Key Features:
  • Pass-Through Options: To use the detailed options from pdf:stamp (like --stamp-position or --watermark-color), you must use the -O flag.
  • Placeholders: The --stamp-qr-string and --watermark-text options support dynamic placeholders that are replaced with data from the document being processed. Supported placeholders: {id} (or _id) and {FCallCode}.
  • Logging: Every stamping operation (success or failure) is recorded in the stamp_logs collection in MongoDB.
  • Debugging: Run the command with the -v flag to see the real-time, detailed output from the pdf:stamp worker command.
Options:
OptionDescription
--id=Process only a single document by its specific ID.
--forceProcess documents even if they have already been stamped (i.e., stamped_at is not null).
--unprocessed-onlyProcess only documents where stamped_at is null. (Default behavior)
--stamp-qr-string=The string for the QR code, supporting placeholders.
--watermark-text=The string for the watermark, supporting placeholders.
-O=Pass a detailed option to the pdf:stamp command. (e.g., -O="stamp-pages=first")
Examples: 
# Apply a QR code with the document's FCallCode to the first page of all unprocessed documents
php artisan documents:generate-stamp --unprocessed-only \
  --stamp-qr-string="{FCallCode}" \
  -O="stamp-pages=first"

# Apply a red, centered "CONFIDENTIAL" watermark to all pages of a single document
php artisan documents:generate-stamp --id=5f11895c7dfdb46efb0d3022 \
  --watermark-text="CONFIDENTIAL" \
  -O="watermark-color=255,0,0" \
  -O="watermark-position=center" \
  -O="watermark-pages=all"

# Combine a stamp and a watermark in a single run with verbose output for 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"

​
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"