BOM UTF-8 di File PHP: Penyebab JSON API Rusak dan Cara Membersihkannya

BOM UTF-8 di file PHP: penyebab JSON API rusak dan cara membersihkannya

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.

Diagram alur BOM UTF-8 dari file PHP ke output buffer sampai respons JSON API rusak di klien
Perjalanan tiga byte BOM dari editor sampai merusak respons JSON di sisi klien.

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 file3 byte pertamaAman untuk PHP?
UTF-8 tanpa BOM3c 3f 70 (<?p)Ya
UTF-8 dengan BOMef bb bfTidak, BOM ikut tercetak
ASCII murni3c 3f 70Ya
UTF-16 LE dengan BOMff fe 3cTidak, 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.

Output xxd menunjukkan BOM UTF-8 ef bb bf di awal respons JSON dan pesan error json_decode, JSON.parse, serta json.loads
Tangkapan asli dari server uji kami: BOM terlihat jelas di xxd, lalu tiga klien berbeda gagal mem-parse JSON (nama user dan host disensor).

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.

Warning headers already sent akibat BOM UTF-8 di config.php serta fatal error strict_types dan namespace di PHP 8.5
Tangkapan asli: BOM memicu warning headers already sent dan dua fatal error di PHP 8.5 (nama user dan host disensor).

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.

Hasil uji skrip cek BOM UTF-8, pembersihan dengan PHP, respons JSON bersih, dan hook git pre-commit menolak file ber-BOM
Tangkapan asli: deteksi, pembersihan, JSON kembali bersih, dan hook git menolak commit ber-BOM (nama user dan host disensor).

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.

Diagram empat lapis pencegahan BOM UTF-8: setelan editor, EditorConfig, hook git pre-commit, dan pemeriksaan sebelum deploy
Empat lapis pencegahan BOM, dari laptop developer sampai server produksi.

Lapis 1: Setelan Editor

EditorSetelan 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 11Save As, pilih “UTF-8” (bukan “UTF-8 with BOM”)
PhpStormSettings, 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 saat composer 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. Pakai str_starts_with() dan substr().
  • 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

Referensi: PHP Manual: json_decode, PHP Manual: headers_sent, PHP Manual: output_buffering, WHATWG Encoding: UTF-8 decode, Git: githooks pre-commit, EditorConfig.

Tinggalkan Balasan

Alamat email Anda tidak akan dipublikasikan. Ruas yang wajib ditandai *