Bayangkan Anda mengirim surat resmi, tetapi petugas pos menempelkan stiker kecil tak terlihat di pojok amplop. Penerima biasa tidak peduli. Namun, mesin sortir otomatis langsung menolak amplop itu karena bentuknya tidak sesuai standar. Begitulah cara kerja BOM UTF-8 di file PHP. Tiga byte tak kasat mata di awal file ikut terkirim ke klien, sehingga browser tetap tenang sementara parser JSON yang ketat langsung menyerah.
Pada artikel ini kami membahas BOM UTF-8 dari kasus nyata di aplikasi billing ISP kami. Saat itu toko voucher tiba-tiba gagal memuat daftar paket karena 45 file PHP tersimpan dengan BOM. Anda akan belajar mengenali gejalanya, mendeteksi file bermasalah dengan xxd dan grep, membersihkannya secara massal, lalu mencegahnya kambuh lewat setelan editor dan hook git. Semua perintah sudah kami uji di server Ubuntu dengan PHP 8.5.

Apa Itu BOM UTF-8?
BOM (Byte Order Mark) adalah penanda tiga byte EF BB BF yang sebagian editor tulis di awal file teks UTF-8. Pada UTF-16, BOM memang berguna untuk menandai urutan byte. Sebaliknya, UTF-8 tidak punya masalah urutan byte, sehingga BOM di sini hanya berfungsi sebagai “tanda tangan” encoding.
Masalahnya, PHP tidak mengenali BOM. Bagi PHP, semua karakter sebelum tag pembuka <?php adalah teks HTML biasa yang harus ia cetak. Akibatnya, setiap kali skrip memanggil require atau include pada file ber-BOM, PHP mengirim tiga byte itu ke output sebelum data apa pun.
| Encoding file | 3 byte pertama | Aman untuk PHP? |
|---|---|---|
| UTF-8 tanpa BOM | 3c 3f 70 (<?p) | Ya |
| UTF-8 dengan BOM | ef bb bf | Tidak, BOM ikut tercetak |
| ASCII murni | 3c 3f 70 | Ya |
| UTF-16 LE dengan BOM | ff fe 3c | Tidak, PHP tidak membaca kodenya |
Lalu dari mana BOM berasal? Biasanya dari editor di Windows. Notepad lama menyimpan “UTF-8” lengkap dengan BOM, sedangkan beberapa editor lain menawarkan opsi “UTF-8 with BOM” yang mudah salah pilih. Selain itu, file hasil salin dari tool Windows tertentu juga sering membawa BOM tanpa Anda sadari.
Gejala BOM UTF-8 di Aplikasi PHP
BOM jarang memunculkan pesan error yang jelas. Oleh karena itu, gejalanya sering menyesatkan dan developer menghabiskan waktu mencari bug di tempat yang salah. Untuk melihat gejalanya secara langsung, kami membuat dua file uji. File config.php berisi BOM, sedangkan api/profiles.php memuat file tersebut lalu mengirim JSON.
<?php
require __DIR__ . '/../config/config.php';
header('Content-Type: application/json');
echo json_encode([
'success' => true,
'data' => [
['name' => 'Paket 10 Mbps', 'price' => 150000],
['name' => 'Paket 20 Mbps', 'price' => 200000],
],
]);
Kode ini terlihat benar sepenuhnya. Namun, begitu baris require berjalan, PHP langsung mencetak BOM dari config.php sebelum json_encode() sempat bekerja. Kemudian kami menjalankan server bawaan PHP dan memeriksa respons mentahnya dengan curl serta xxd.
cd app php -d output_buffering=4096 -S 127.0.0.1:8099 & curl -s -i http://127.0.0.1:8099/api/profiles.php curl -s http://127.0.0.1:8099/api/profiles.php | xxd | head -3
Gejala 1: JSON.parse dan json_decode Gagal
Respons dari endpoint tadi selalu diawali ef bb bf sebelum kurung kurawal pembuka. Sekilas JSON-nya tampak normal, karena terminal dan browser tidak menampilkan BOM. Namun, parser JSON yang ketat menganggap byte tersebut sebagai karakter ilegal.

Dari screenshot di atas, PHP json_decode() hanya melaporkan Syntax error. Sementara itu, Node.js menampilkan pesan khas Unexpected token dan Python lebih jujur dengan menyebut Unexpected UTF-8 BOM. Klien PHP sederhana berikut cukup untuk membuktikannya.
<?php
$url = $argv[1] ?? 'http://127.0.0.1:8099/api/profiles.php';
$response = file_get_contents($url);
$decoded = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
echo "JSON error : " . json_last_error_msg() . "\n";
echo "3 byte awal: " . bin2hex(substr($response, 0, 3)) . "\n";
exit(1);
}
echo "OK, jumlah paket: " . count($decoded['data']) . "\n";
Perhatikan baris bin2hex(substr($response, 0, 3)). Baris ini mencetak tiga byte pertama respons dalam bentuk heksadesimal, sehingga Anda langsung tahu apakah BOM menjadi biang keroknya. Kami sangat menyarankan baris serupa di log setiap klien API.
Kenapa Browser Kadang Tidak Bermasalah?
Uniknya, fetch().json() di browser dan di Node.js 22 justru berhasil. Standar WHATWG Encoding memerintahkan browser membuang BOM saat mengubah byte menjadi teks. Akibatnya, halaman web yang memanggil API lewat fetch sering tampak sehat, sedangkan integrasi server-ke-server yang memakai PHP json_decode(), modul http Node.js, atau Python gagal total. Perbedaan inilah yang membuat bug BOM terasa “hanya terjadi di sebagian klien”.
Gejala 2: Warning Headers Already Sent
Gejala kedua muncul saat output_buffering bernilai 0. Dalam kondisi ini PHP langsung mengirim BOM ke klien, sehingga header HTTP ikut terkunci. Selanjutnya, setiap panggilan header(), setcookie(), atau session_start() menghasilkan warning terkenal ini.
Warning: Cannot modify header information - headers already sent by (output started at /tmp/bomdemo/app/config/config.php:1) in /tmp/bomdemo/app/api/profiles.php on line 4
Kuncinya ada pada bagian output started at ... config.php:1. PHP memberi tahu file dan baris persis yang pertama kali mencetak output. Jika baris itu baris 1 dan Anda tidak melihat karakter apa pun di sana, hampir pasti penyebabnya BOM.
Gejala 3: Fatal Error strict_types dan Namespace
Gejala ketiga paling keras. Jika file ber-BOM berisi declare(strict_types=1) atau namespace, PHP menolak menjalankannya karena kedua pernyataan itu wajib menjadi pernyataan pertama. Bagi PHP, BOM sudah terhitung sebagai output sebelum pernyataan tersebut.

Selain itu, perhatikan bahwa php -l tetap melaporkan No syntax errors detected untuk file ber-BOM. Dengan demikian, pemeriksa sintaks biasa tidak akan menyelamatkan Anda.
Kenapa Produksi Tidak Menampilkan Warning?
Di server produksi kami, gejala kedua justru tidak pernah muncul. Ternyata php.ini bawaan Ubuntu untuk php-fpm memasang output_buffering = 4096. PHP menampung BOM di buffer dulu, sehingga header() masih sempat berjalan tanpa warning. Namun, buffer tetap mengirim BOM bersama JSON. Akibatnya, API terlihat normal di log server, tetapi klien tetap menerima JSON yang rusak.
Contoh Kasus 1: Toko Voucher Gagal Memuat Paket
Kasus ini benar-benar terjadi pada 24 Mei 2026. Toko voucher hotspot milik salah satu ISP pelanggan kami tiba-tiba menampilkan pesan “Respons server tidak valid” saat memuat daftar paket. Toko ini mengambil data dari API billing lewat cURL, lalu mem-parse hasilnya dengan json_decode(). Berikut potongan asli fungsi parser di model toko voucher.
$decoded = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
log_message('error', "Voucher_api_model JSON error. HTTP {$code}. Response: " . substr($response, 0, 200));
return [
'success' => false,
'message' => 'Respons server tidak valid. (HTTP ' . $code . ')',
'data' => null,
];
}
Log seperti ini menyesatkan. Kode HTTP-nya 200 dan potongan respons tampak seperti JSON sempurna, karena BOM tidak terlihat di file log. Setelah kami memeriksa byte awal respons, barulah penyebabnya terlihat. Sebanyak 22 file PHP di aplikasi billing utama dan 23 file di versi PWA ternyata diawali BOM. Kami membersihkan seluruh file dengan perintah satu baris di bagian berikutnya, dan toko voucher langsung normal tanpa perubahan kode API sama sekali.
Cara Mendeteksi BOM UTF-8
Untuk satu file, cara tercepat adalah membaca tiga byte pertamanya. Perintah xxd dan hexdump menampilkan byte dalam bentuk heksadesimal, sedangkan file langsung menyebut encoding-nya.
head -c 3 config/config.php | xxd # 00000000: efbb bf ... head -c 16 config/config.php | hexdump -C # 00000000 ef bb bf 3c 3f 70 68 70 0a 2f 2f 20 6b 6f 6e 66 |...<?php.// konf| file config/config.php clean.php # config/config.php: PHP script, Unicode text, UTF-8 (with BOM) text # clean.php: PHP script, ASCII text
Jika xxd tidak tersedia, Anda bisa memakai od yang hampir selalu terpasang. Kami memakai loop berikut saat mengaudit folder view error CodeIgniter. File sehat menampilkan 3c3f70, sedangkan file ber-BOM menampilkan efbbbf.
for f in app/*.php app/config/*.php; do bom=$(head -c3 "$f" | od -An -tx1 | tr -d " \n") printf "%-22s %s\n" "$(basename $f)" "$bom" done # clean.php 3c3f70 # helpers.php efbbbf # config.php efbbbf
Memindai Seluruh Proyek dengan grep
Untuk satu proyek penuh, grep jauh lebih praktis. Sintaks $'\xEF\xBB\xBF' membuat Bash mengubah teks escape menjadi tiga byte BOM yang sebenarnya.
# semua file PHP yang mengandung BOM di posisi mana pun grep -rl $'\xEF\xBB\xBF' --include="*.php" . # hanya BOM di awal baris, tanpa folder vendor grep -rlI --include="*.php" --exclude-dir=vendor $'^\xEF\xBB\xBF' .
Perintah pertama juga menemukan BOM di tengah file, misalnya hasil menempelkan potongan teks dari dokumen lain. Sebaliknya, perintah kedua lebih fokus dan melewati folder vendor. Folder itu milik Composer, jadi sebaiknya Anda tidak mengubahnya secara manual.
Skrip Pemeriksa yang Siap Pakai
Kemudian kami membungkus pemeriksaan ke dalam skrip kecil yang memberi exit code. Exit code 1 berarti ada file ber-BOM, sehingga skrip ini cocok untuk CI atau langkah sebelum deploy.
#!/usr/bin/env bash
# cek-bom.sh - daftar file PHP yang diawali BOM UTF-8 (EF BB BF)
DIR="${1:-.}"
total=0
while IFS= read -r -d '' f; do
if [ "$(head -c 3 "$f" | xxd -p)" = "efbbbf" ]; then
echo "BOM: $f"
total=$((total + 1))
fi
done < <(find "$DIR" -type f -name '*.php' -not -path '*/vendor/*' -print0)
echo "Total file ber-BOM: $total"
[ "$total" -eq 0 ]
Pasangan -print0 dan read -d '' menjaga skrip tetap aman untuk nama file yang mengandung spasi. Baris terakhir menentukan exit code, yaitu sukses hanya jika total file ber-BOM bernilai nol.
Membersihkan BOM UTF-8 Secara Massal
Setelah tahu file mana yang bermasalah, langkah berikutnya adalah membuang tiga byte tersebut. Kami menyiapkan dua cara, yaitu memakai sed dan memakai PHP. Pilih sesuai alat yang tersedia di server Anda.
Cara 1: sed di Linux
Pertama, ini perintah satu baris yang kami pakai untuk menyapu folder aplikasi billing saat insiden. Perintah ini hanya mengubah file yang benar-benar diawali BOM.
find /path/proyek -name "*.php" -not -path "*/vendor/*" -print0 | xargs -0 -I{} sh -c 'head -c 3 {} | xxd -p | grep -q efbbbf && sed -i "1s/^\xEF\xBB\xBF//" {} && echo stripped: {}'
Ekspresi 1s/^\xEF\xBB\xBF// berarti “di baris 1 saja, hapus tiga byte BOM di awal baris”. Selanjutnya, untuk pemakaian rutin kami lebih suka versi skrip yang membuat cadangan .bak-bom sebelum mengubah file.
#!/usr/bin/env bash
# bersihkan-bom.sh - buang BOM dari baris pertama setiap file PHP
DIR="${1:-.}"
find "$DIR" -type f -name '*.php' -not -path '*/vendor/*' -print0 |
while IFS= read -r -d '' f; do
if [ "$(head -c 3 "$f" | xxd -p)" = "efbbbf" ]; then
cp -p "$f" "$f.bak-bom"
sed -i '1s/^\xEF\xBB\xBF//' "$f"
echo "dibersihkan: $f"
fi
done
Opsi cp -p mempertahankan izin dan waktu modifikasi file cadangan. Setelah aplikasi terbukti normal, Anda bisa menghapus semua cadangan dengan find . -name '*.bak-bom' -delete.
Cara 2: Skrip PHP untuk Hosting Tanpa SSH Penuh
Di shared hosting atau di Windows, sed belum tentu tersedia. Oleh karena itu, kami juga menulis versi PHP yang berjalan di mana saja. Tanpa opsi --fix, skrip ini hanya melapor.
<?php
// bom-clean.php - pindai dan buang BOM UTF-8 dari file PHP
// Pakai: php bom-clean.php /path/proyek [--fix]
$dir = $argv[1] ?? '.';
$fix = in_array('--fix', $argv, true);
$bom = "\xEF\xBB\xBF";
$found = 0;
$it = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($dir, FilesystemIterator::SKIP_DOTS)
);
foreach ($it as $file) {
$path = $file->getPathname();
if ($file->getExtension() !== 'php' || str_contains($path, '/vendor/')) {
continue;
}
$fh = fopen($path, 'rb');
$head = fread($fh, 3);
fclose($fh);
if ($head !== $bom) {
continue;
}
$found++;
if ($fix) {
$isi = file_get_contents($path);
file_put_contents($path, substr($isi, 3), LOCK_EX);
echo "dibersihkan: $path\n";
} else {
echo "BOM: $path\n";
}
}
echo $fix ? "Selesai, $found file dibersihkan.\n" : "Ditemukan $found file ber-BOM (jalankan dengan --fix).\n";
exit($found > 0 && !$fix ? 1 : 0);
Skrip ini membaca tiga byte pertama lewat fopen agar tetap ringan untuk file besar. Kemudian substr($isi, 3) membuang BOM, dan LOCK_EX mencegah dua proses menulis file yang sama bersamaan.
Hasil Uji Pembersihan
Kami menguji kedua cara pada folder demo yang sama, lalu memastikan endpoint API kembali mengirim JSON bersih. Hasilnya terlihat pada screenshot berikut.

Mencegah BOM Kembali Masuk
Membersihkan BOM itu mudah. Namun, BOM sangat gampang kambuh. Kami sendiri menemukannya lagi dua bulan kemudian. Karena itu, pencegahan perlu berlapis, mulai dari editor sampai repository.

Lapis 1: Setelan Editor
| Editor | Setelan yang benar |
|---|---|
| VS Code | "files.encoding": "utf8" (bukan utf8bom), cek pojok kanan bawah status bar |
| Notepad++ | Menu Encoding, pilih “UTF-8” (bukan “UTF-8-BOM”) |
| Notepad Windows 11 | Save As, pilih “UTF-8” (bukan “UTF-8 with BOM”) |
| PhpStorm | Settings, File Encodings, Create UTF-8 files: “with NO BOM” |
Lapis 2: EditorConfig di Repository
Setelan editor bergantung pada masing-masing developer. Sebaliknya, file .editorconfig ikut tersimpan di repository dan mayoritas editor membacanya otomatis. Nilai charset = utf-8 berarti UTF-8 tanpa BOM, sedangkan BOM memakai nilai utf-8-bom.
root = true [*] charset = utf-8 end_of_line = lf insert_final_newline = true [*.php] indent_style = space indent_size = 4
Lapis 3: Hook git pre-commit
Hook ini menjadi penjaga terakhir sebelum kode masuk repository. Simpan sebagai .git/hooks/pre-commit, lalu beri izin eksekusi dengan chmod +x.
#!/bin/sh
# .git/hooks/pre-commit - tolak commit jika ada file PHP ber-BOM
gagal=0
for f in $(git diff --cached --name-only --diff-filter=ACM -- '*.php'); do
if [ "$(git show ":$f" | head -c 3 | xxd -p)" = "efbbbf" ]; then
echo "DITOLAK: $f diawali BOM UTF-8"
gagal=1
fi
done
if [ "$gagal" -eq 1 ]; then
echo "Bersihkan dulu: sed -i '1s/^\xEF\xBB\xBF//' <file>"
exit 1
fi
Bagian git show ":$f" membaca versi file di staging area, bukan file di disk. Dengan begitu, hook memeriksa persis isi yang akan masuk commit. Pada uji kami, commit pertama langsung tertolak, sedangkan commit kedua lolos setelah sed membersihkan file.
Lapis 4: Pemeriksaan Sebelum Deploy dan Klien Defensif
Terakhir, jalankan cek-bom.sh di pipeline deploy. Selain itu, buat klien API Anda sedikit lebih toleran. Kode berikut hanya membuang BOM jika tiga byte pertama memang BOM.
$response = file_get_contents("http://127.0.0.1:8099/api/profiles.php");
// buang BOM hanya jika 3 byte pertama memang BOM
if (str_starts_with($response, "\xEF\xBB\xBF")) {
$response = substr($response, 3);
}
$decoded = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
Contoh Kasus 2: BOM Kambuh di Halaman Error
Pada 16 Juli 2026, log aplikasi PWA kami penuh dengan error dari view error_404.php. Saat mengaudit folder views/errors/html dengan loop od tadi, kami menemukan error_404.php dan error_general.php versi PWA kembali ber-BOM. Menariknya, versi yang sama di aplikasi utama tetap bersih. Artinya, pembersihan massal Mei lalu tidak menjamin file baru atau file hasil sinkron berikutnya ikut bersih. Kami membuang BOM dari kedua file sekaligus memperbaiki bug lain yang kebetulan ada di file yang sama. Pelajarannya jelas, yaitu pembersihan sekali jalan tidak cukup tanpa lapis pencegahan seperti hook git dan pemeriksaan sebelum deploy.
Kesalahan Umum
- Mencari bug di kode API. Developer sering membongkar
json_encode(), padahal biang keroknya file konfigurasi yang ikut ter-include. - Percaya pada tampilan browser.
fetch().json()membuang BOM, jadi uji di browser bisa lolos sementara klien server-ke-server gagal. - Menutup gejala dengan
ob_clean(). Cara ini menyembunyikan masalah. Bersihkan file sumbernya. - Menyunting folder
vendor. Perubahan hilang saatcomposer install. Laporkan ke pembuat paket jika memang ada BOM di sana. - Memakai
ltrim($s, "\xEF\xBB\xBF")tanpa sadar. Fungsi ini membuang setiap byte EF, BB, atau BF satu per satu, bukan urutan BOM utuh. Pakaistr_starts_with()dansubstr(). - Mengandalkan
php -l. Pemeriksa sintaks PHP tidak menganggap BOM sebagai kesalahan. - Lupa reload php-fpm. Jika opcache memakai
validate_timestamps=0, server tetap menjalankan versi lama sampai php-fpm reload.
Kesimpulan
BOM UTF-8 hanyalah tiga byte, tetapi dampaknya besar. BOM membuat json_decode() dan JSON.parse gagal, memicu warning headers already sent, bahkan menggagalkan file yang memakai strict_types atau namespace. Kuncinya ada pada kebiasaan memeriksa tiga byte pertama, baik di file maupun di respons API.
Singkatnya, deteksi dengan xxd atau grep, bersihkan dengan sed atau skrip PHP, lalu cegah lewat setelan editor, .editorconfig, dan hook git pre-commit. Dengan empat lapis itu, kasus seperti toko voucher kami tidak perlu terulang di proyek Anda.
Baca Juga
- PHP JSON: Encode dan Decode Data JSON
- Cara Mengembalikan JSON dari Skrip PHP
- PHP Include: Menyisipkan File dengan include dan require
Referensi: PHP Manual: json_decode, PHP Manual: headers_sent, PHP Manual: output_buffering, WHATWG Encoding: UTF-8 decode, Git: githooks pre-commit, EditorConfig.

