Complete Tutorial: Automating Official Letter Templates with Laravel & Dompdf

In a dynamic operational environment such as a hospital, clinic, or company with a high volume of document transactions, administrative efficiency is key. Imagine if every official letter, from patient referral letters, internal memos, certificates, to decrees, had to be created manually. This process not only takes hours every day, but is also highly prone to typographical errors, format mismatches, and data inconsistencies. Our internal data shows that administrative teams at medium-sized healthcare facilities can spend up to 30% of their working time just preparing and reviewing manual documents, resulting in service delays and higher operational costs. Nugroho Setiawan, with extensive experience in SIMRS and E-Office development, fully understands this challenge. This article will guide you, IT Managers, clinic owners, and Operations Managers, through a practical and in-depth tutorial on how to build an automation system for official letter templates. We will utilize modern web technologies such as Laravel for the backend and Dompdf for PDF document generation, ensuring every outgoing letter is accurate, consistent, and efficient. With the right implementation, you can reduce document creation time by up to 80%, minimize errors, and shift your team's focus to more strategic tasks.

Basic Concepts of Official Letter Automation: Why Is It Important?

Official letter automation is no longer a luxury, but an essential need for organizations that want to achieve maximum operational efficiency and high data integrity. At its core, automation involves using software to fill relevant data into predefined document templates, then generate the final document in the desired format such as PDF or DOCX. Imagine a clinic that every day issues dozens of laboratory examination referral letters or referral letters to other hospitals. If patient data, referring doctor, date, and destination must be retyped every time, the risk of errors is very high. An internal study shows that the manual writing error rate can reach 5-7% per document, potentially causing miscommunication and even legal problems.

The main benefits of this automation include increased consistency in letter format and content, reduced time spent on repetitive administrative tasks, and minimization of human error. This system also enables a better audit trail, where each generated letter can be traced to who created it, when, and with what data. This is crucial for meeting hospital accreditation standards or health regulations such as those set by the Ministry of Health of the Republic of Indonesia, for example in Minister of Health Regulation (PMK) Number 24 of 2022 concerning Medical Records, which emphasizes the importance of accurate and integrated documentation.

The key components of an official letter automation system include:

• Central Database: To store all necessary data (patient data, doctors, staff, letter types, etc.).
• Template Engine: A mechanism to combine data from the database with the letter template structure.
• User Interface (UI): A web or desktop application that allows users to select the letter type, enter dynamic data, and trigger the letter creation process.
• Document Generation: A module responsible for converting the data-filled template into the final document format (PDF, DOCX).

By integrating this system into the existing IT ecosystem, such as SIMRS (Hospital Management Information System) or E-Office, organizations can create a seamless workflow. For example, patient data already in SIMRS can be directly pulled to fill in a referral letter, without the need for re-entry. This not only saves administrative time, but also ensures that the data used is the most up-to-date and accurate from a single source. This automation implementation can result in operational cost savings of up to 20-25% per year from reduced administrative work hours and unnecessary printing costs.

Technical Implementation Details: Building with Laravel & Dompdf

To build a robust and scalable official letter automation system, we will utilize a combination of proven web technologies. Our technology stack choices include:

• Backend: Laravel Framework (version 11.x), with PHP (version 8.2 or higher). Laravel provides a powerful ecosystem for API development, database management, and business logic.
• Database: PostgreSQL (version 16). PostgreSQL is known for its reliability, data integrity, and ability to handle large data volumes, making it very suitable for sensitive data in healthcare environments.
• PDF Generation: Dompdf (version 2.0.x). This is a very popular PHP library for converting HTML and CSS into PDF documents, ideal for generating official letters with complex layouts.
• Frontend (Optional, for UI): Vue.js (version 3.x) or React (version 18.x). Although this tutorial will focus more on the backend side and document generation, Vue.js or React can be used to build an interactive and responsive user interface for letter data input.

The implementation steps generally include:

1. Database Schema Design: We need a table to store the types of letters (for example, 'Referral Letter', 'Internal Memo', 'Doctor's Certificate'), as well as a table for the letter data itself that will store dynamic information such as letter number, date, recipient, subject, and specific content. An example structure of the surat_dinas table would include id, jenis_surat_id, nomor_surat, tanggal_surat, perihal, konten_html, penerima, penanda_tangan, and status.
2. API Development with Laravel: Creating RESTful API endpoints for CRUD (Create, Read, Update, Delete) of letter data. This will involve creating Eloquent models, controllers, and secure API routes. Input data validation is very important at this stage to ensure data integrity. For example, ensuring the letter number is unique or the letter date is in the correct format.
3. Creating Dynamic HTML Templates: Each type of letter will have its own HTML template stored in the database or as a Laravel Blade view file. This template will have placeholders (for example, {{ $nomor_surat }}, {{ $penerima }}) that will be filled with data from the database when the letter is created.
4. Dompdf Integration: Using Dompdf to take the HTML that has been filled with data, then convert it into a PDF file. This involves configuring Dompdf to handle CSS and layout so that the PDF output matches the desired design. It should be noted that Dompdf has limitations in rendering very complex CSS, so the template design must be adjusted.
5. Security & Authentication: Implementing an authentication system (for example, Laravel Sanctum for the API) and authorization (for example, using Spatie Laravel Permission) to ensure that only authorized users can create or view official letters.

With this approach, a hospital can manage thousands of referral letters per month with unprecedented efficiency. For example, RSUD Dr. Soetomo Surabaya, which serves thousands of patients every day, can save hundreds of work hours monthly just from automating referral letters and inpatient certificates, reducing queues in the administration department and speeding up the overall patient service process.

Implementation Code Example: Database Schema & PDF Generation

To provide a more concrete picture, let's look at an implementation code example. First, we will create a database migration for the surat_dinas table using Laravel. This is the foundation where all letter information will be stored. Make sure you have installed Laravel 11.x and configured the database connection to PostgreSQL 16.

Code 1: Database Migration for the surat_dinas Table

<?php%0Ause Illuminate\Database\Migrations\Migration;%0Ause Illuminate\Database\Schema\Blueprint;%0Ause Illuminate\Support\Facades\Schema;%0A%0Areturn new class extends Migration%0A{%0A    /**%0A     * Run the migrations.%0A     */%0A    public function up(): void%0A    {%0A        Schema::create('surat_dinas', function (Blueprint $table) {%0A            $table->id();%0A            $table->unsignedBigInteger('jenis_surat_id'); // Foreign key ke tabel jenis_surat%0A            $table->string('nomor_surat')->unique();%0A            $table->date('tanggal_surat');%0A            $table->string('perihal');%0A            $table->text('konten_html'); // Konten surat dalam format HTML%0A            $table->string('penerima');%0A            $table->string('penanda_tangan');%0A            $table->string('jabatan_penanda_tangan');%0A            $table->enum('status', ['draft', 'terkirim', 'selesai', 'dibatalkan'])->default('draft');%0A            $table->unsignedBigInteger('created_by')->nullable(); // Foreign key ke tabel users%0A            $table->timestamps();%0A%0A            $table->foreign('jenis_surat_id')->references('id')->on('jenis_surat')->onDelete('cascade');%0A            $table->foreign('created_by')->references('id')->on('users')->onDelete('set null');%0A        });%0A%0A        // Contoh tabel jenis_surat (jika belum ada)%0A        Schema::create('jenis_surat', function (Blueprint $table) {%0A            $table->id();%0A            $table->string('nama_jenis');%0A            $table->text('template_html'); // Template dasar untuk jenis surat ini%0A            $table->timestamps();%0A        });%0A    }%0A%0A    /**%0A     * Reverse the migrations.%0A     */%0A    public function down(): void%0A    {%0A        Schema::dropIfExists('surat_dinas');%0A        Schema::dropIfExists('jenis_surat');%0A    }%0A};%0A

The migration above defines the surat_dinas table with important columns such as nomor_surat, tanggal_surat, perihal, and konten_html. The jenis_surat_id column is a foreign key that refers to the jenis_surat table, which stores the basic HTML template for each type of letter. The created_by column is also added for audit trail, pointing to the users table (assuming you have a users table). After the migration is run (php artisan migrate), you will have a ready database structure.

Next, let's look at how we can create a controller in Laravel to generate official letters and convert them into PDF using Dompdf. First, make sure you have installed Dompdf via Composer: composer require dompdf/dompdf:^2.0.

Code 2: Controller for Letter & PDF Generation

<?php%0Anamespace App\Http\Controllers;%0A%0Ause Illuminate\Http\Request;%0Ause App\Models\SuratDinas;%0Ause App\Models\JenisSurat;%0Ause Dompdf\Dompdf;%0Ause Dompdf\Options;%0Ause Illuminate\Support\Facades\View;%0Ause Illuminate\Support\Facades\Storage;%0A%0Aclass SuratDinasController extends Controller%0A{%0A    public function generatePdf(string $id)%0A    {%0A        $surat = SuratDinas::with('jenisSurat')->findOrFail($id);%0A%0A        // Data yang akan diisi ke template%0A        $data = [%0A            'nomor_surat' => $surat->nomor_surat,%0A            'tanggal_surat' => \Carbon\Carbon::parse($surat->tanggal_surat)->translatedFormat('d F Y'),%0A            'perihal' => $surat->perihal,%0A            'konten' => $surat->konten_html, // Konten spesifik surat%0A            'penerima' => $surat->penerima,%0A            'penanda_tangan' => $surat->penanda_tangan,%0A            'jabatan_penanda_tangan' => $surat->jabatan_penanda_tangan,%0A            'nama_jenis_surat' => $surat->jenisSurat->nama_jenis,%0A            // Tambahkan data lain sesuai kebutuhan template%0A        ];%0A%0A        // Render template HTML dengan data%0A        // Asumsi template disimpan di resources/views/templates/surat_dinas_template.blade.php%0A        // Atau bisa juga langsung dari $surat->jenisSurat->template_html jika disimpan di DB%0A        $html = View::make('templates.surat_dinas_template', $data)->render();%0A%0A        // Konfigurasi Dompdf%0A        $options = new Options();%0A        $options->set('isHtml5ParserEnabled', true);%0A        $options->set('isRemoteEnabled', true); // Untuk mengizinkan gambar dari URL eksternal%0A%0A        $dompdf = new Dompdf($options);%0A        $dompdf->loadHtml($html);%0A        $dompdf->setPaper('A4', 'portrait'); // Ukuran kertas A4, orientasi portrait%0A        $dompdf->render();%0A%0A        // Menyimpan atau menampilkan PDF%0A        $filename = 'surat_dinas_' . $surat->nomor_surat . '.pdf';%0A        // Simpan ke storage%0A        Storage::put('public/surat_dinas/' . $filename, $dompdf->output());%0A%0A        // Atau langsung download%0A        return $dompdf->stream($filename);%0A    }%0A}%0A

In this SuratDinasController controller, the generatePdf function takes the letter ID, retrieves the letter data from the database, then fills that data into a Blade template (or directly into an HTML string if the template is stored in the DB). After the HTML is filled, Dompdf converts it to PDF. You can choose to save the PDF file to server storage or make it directly available for download by the user. Make sure you have the view resources/views/templates/surat_dinas_template.blade.php containing your letter's HTML structure with Blade placeholders.

Example Payload & API Error Handling

When interacting with this official letter automation system via API, it is important to understand the expected data structure (payload) and how the system handles errors. The following is an example JSON payload for creating a new official letter via your Laravel API endpoint.

Example JSON Payload for Creating an Official Letter:

The following is an example JSON payload that you can send to the POST /api/surat-dinas endpoint:

{
  "nomor_surat": "005/123/DPK/2024",
  "tanggal_surat": "2024-06-15",
  "perihal": "Undangan Rapat Koordinasi",
  "tujuan": "Kepala Dinas Pendidikan",
  "isi_surat": "Dengan hormat, sehubungan dengan...",
  "penandatangan": "Dr. Budi Santoso, M.Si",
  "jabatan_penandatangan": "Kepala Dinas"
}

If a validation error occurs, Laravel will return a 422 Unprocessable Entity response with details of the problematic fields. For internal errors such as Dompdf rendering failures, you should wrap the generation process in a try-catch block and return a 500 response with an informative message, for example: {"error": "Gagal membuat PDF, periksa template atau data surat."}. That way, API clients can handle errors programmatically without having to guess the cause.

Practical Optimization and Maintenance Tips

1. Use caching for templates and configuration. If your letter templates rarely change, store the compiled Blade results or HTML content in the Laravel cache. This will significantly speed up the PDF generation process, especially under high demand. Also, avoid loading external images directly from URLs; download and save images locally or use base64 so Dompdf does not wait for slow network connections.

2. Manage fonts and file size wisely. Dompdf requires registered fonts for special characters. Use standard fonts such as DejaVu Sans or register custom fonts via @font-face in CSS. Also pay attention to image size and table complexity; the lighter the HTML, the faster the render and the smaller the resulting PDF file size. For documents with many pages, consider splitting them into several files or using the appropriate setPaper option.

3. Apply versioning to letter templates. Store each template version in the database or a separate folder with a version marker. When there is a change in letter format, you can still regenerate old letters with the template version from that time. This is important for audits and administrative compliance. Do not forget to always back up letter and template data regularly, and test the PDF generation process in a staging environment before deploying it to production.

FAQ

Does Dompdf support CSS Flexbox or Grid?

Not entirely. Dompdf has limited CSS support and has not fully implemented Flexbox or Grid. For official letter layout, you should use classic layout techniques such as float, table, or inline-block that have proven stable. If you need complex layouts, consider switching to another library such as Snappy (wkhtmltopdf) or Browsershot (Puppeteer).

How do I add headers and footers with page numbers?

You can utilize the <script type="text/php"> feature in Dompdf to write PHP code that prints page numbers, or use CSS @page with margins and repeating elements. Simple example: add <div style="position: fixed; bottom: 0; width: 100%; text-align: center;">Halaman {PAGE_NUM} dari {PAGE_COUNT}</div> in your template. Dompdf will replace that placeholder automatically.

Why does the generated PDF look different from the display in the browser?

This difference is common because Dompdf's rendering engine is not the same as a browser. Make sure you use compatible CSS, avoid modern properties, and set margin and padding explicitly. Perform repeated print tests and adjust the stylesheet specifically for PDF (pdf.css) so the results are consistent.

Can I generate PDFs in bulk (batch)?

Yes. You can loop through letter data, call the generate function for each letter, and then combine them into a single ZIP file or merge PDFs with a library such as setasign/fpdi. However, pay attention to memory and execution time limits; for large numbers, use Laravel queue jobs so the process runs in the background without burdening user requests.

Conclusion

Automating official letter templates with Laravel and Dompdf is an efficient solution that combines the ease of Blade, the power of Eloquent, and the flexibility of Dompdf. By following this tutorial, you have learned how to set up a project, create templates, fill in data, generate PDFs, and handle APIs and errors. Apply the practical tips above to maintain the performance and quality of your documents. If you want to deepen the implementation or face special needs such as digital signatures, e-office integration, or migration to a more scalable system, our team is ready to help. Consult your official letter automation needs now and get the right solution for your institution.

This article is part of the education by Nugroho Setiawan, an IT consultant in Jogja. Related solutions: SIMRS SIM Klinik E-Office. Need free consultation?