Exit Codes

Setiap skrip command line berkomunikasi lewat dua saluran sekaligus: teks di layar untuk manusia, dan satu angka — exit code — untuk mesin. Angka tersebut disimpan shell dalam variabel $? begitu proses selesai dan menjadi dasar bagi &&, ||, skrip shell, hingga seluruh sistem CI untuk memutuskan langkah berikutnya. Skrip yang mengabaikan exit code akan merusak otomasi diam-diam: pipeline tampak berhasil padahal data gagal diproses. Pada chapter ini kita akan mempelajari konvensinya, jebakan yang paling sering menjerat penulis PHP, serta cara merangkai perintah berdasarkan keberhasilannya.

Konvensi Nol Berarti Berhasil #

Exit code 0 berarti sukses; setiap nilai selain 0 berarti gagal. Skrip PHP yang selesai normal tanpa exit() otomatis keluar dengan kode 0, tetapi menuliskannya secara eksplisit membuat niat kode lebih jelas:

<?php
echo "Menyiapkan berkas laporan...\n";
echo "Selesai.\n";
exit(0);

Output yang Dihasilkan:

Menyiapkan berkas laporan...
Selesai.

Shell menangkap kode tersebut melalui variabel $? yang selalu memuat exit code perintah terakhir:

php laporan.php
echo "exit code: $?"

Output yang Dihasilkan:

Menyiapkan berkas laporan...
Selesai.
exit code: 0

Konvensi ini universal di seluruh sistem operasi turunan Unix — dari ls sampai git, semua program berjanji hal yang sama. Karena itu skrip PHP kita juga wajib menepatinya.

Kode Non-Nol untuk Kegagalan #

Ketika validasi gagal atau berkas tidak ditemukan, skrip harus keluar dengan kode non-nol — nilai 1 adalah pilihan umum untuk kegagalan generik. Skrip registrasi.php berikut menerima umur sebagai argumen dan menolak nilai di bawah 13:

<?php
$umur = (int) ($argv[1] ?? "0");

if ($umur < 13) {
    fwrite(STDERR, "Galat: umur $umur tidak diizinkan untuk registrasi\n");
    exit(1);
}

echo "Registrasi diterima untuk umur $umur tahun\n";

Output yang Dihasilkan:

Registrasi diterima untuk umur 17 tahun

Alurnya sederhana: argumen dikonversi ke integer, dicek syaratnya, dan cabang kegagalan menulis pesan ke STDERR sebelum keluar dengan exit(1). Perhatikan perilakunya di kedua jalur:

php registrasi.php 17
echo "exit code: $?"

Output yang Dihasilkan:

Registrasi diterima untuk umur 17 tahun
exit code: 0

php registrasi.php 9
echo "exit code: $?"

Output yang Dihasilkan:

Galat: umur 9 tidak diizinkan untuk registrasi
exit code: 1

Karena pesan galat dikirim ke stderr, kode keluarnya tetap 1 meski seluruh diagnostik dibuang — kode adalah kontrak yang tidak terpengaruh tampilan:

php registrasi.php 9 2> /dev/null
echo "exit code: $?"

Output yang Dihasilkan:

exit code: 1

Jebakan exit dengan String #

Fungsi exit() menerima dua jenis parameter yang perilakunya sangat berbeda — dan di sinilah jebakan klasik PHP berada. exit(int) menetapkan exit code; exit(string) justru mencetak string tersebut ke stdout lalu keluar dengan kode 0:

<?php
echo "Menyimpan laporan...\n";
exit("Laporan tersimpan\n");

Output yang Dihasilkan:

Menyimpan laporan...
Laporan tersimpan

Kedua baris tercetak ke stdout — termasuk string pada exit() — dan proses berakhir dengan kode 0. Mari kita buktikan kodenya:

php simpan.php
echo "exit code: $?"

Output yang Dihasilkan:

Menyimpan laporan...
Laporan tersimpan
exit code: 0

Penulis yang mengira exit("pesan galat") akan menandai kegagalan justru mendapat kebalikannya: pesan tampil bagaikan hasil kerja sukses dan pipeline berlanjut seolah tidak ada yang salah.

Kode yang Perlu Anda Kenal #

Secara historis nilai 0-125 tersedia bagi aplikasi, sementara beberapa angka punya makna khusus yang dihormati shell:

PHP memakai 255 sebagai tanda galat fatal — galat yang menghentikan skrip sebelum sempat memanggil exit(). Contoh berikut melempar exception yang tidak tertangkap:

<?php
function bagi(float $a, float $b): float
{
    if ($b === 0.0) {
        throw new InvalidArgumentException("Pembagi tidak boleh nol");
    }
    return $a / $b;
}

echo bagi(10, 0);

Sistem verifikasi chapter mengonfirmasi kode keluarnya tepat 255. Di terminal, tampilan lengkapnya terlihat seperti ini (path dan nomor baris menyesuaikan lokasi berkas di komputer Anda):

php fatal.php
echo "exit code: $?"

Output yang Dihasilkan:

Fatal error: Uncaught InvalidArgumentException: Pembagi tidak boleh nol in /tmp/clitest/fatal.php:5
Stack trace:
#0 /tmp/clitest/fatal.php(10): bagi(10.0, 0.0)
#1 {main}
  thrown in /tmp/clitest/fatal.php on line 5
exit code: 255

Satu detail terakhir yang sering mengejutkan: nilai exit code disimpan dalam satu byte, sehingga hasilnya dihitung modulo 256. Nilai negatif menjadi positif dan nilai besar terpotong:

php -r 'exit(-1);'; echo "exit code: $?"
php -r 'exit(300);'; echo "exit code: $?"

Output yang Dihasilkan:

exit code: 255
exit code: 44

exit(-1) berubah menjadi 255, dan exit(300) terpotong menjadi 44 — sementara exit(256) bahkan kembali menjadi 0. Gunakan hanya nilai 0 sampai 255, dan untuk keamanan maksimal tetap di 0, 1, dan 2.

Merangkai Perintah dengan && dan || #

Nilai exit code benar-benar hidup saat shell merangkai perintah. Operator && menjalankan perintah berikutnya hanya bila perintah sebelumnya keluar 0; operator || sebaliknya — berjalan hanya saat perintah sebelumnya gagal:

php migrasi.php && php kirim-laporan.php

Output yang Dihasilkan:

Migrasi basis data selesai.
Skema versi 3 aktif.
Laporan dikirim ke [email protected].

Rantai && berhenti pada kegagalan pertama. Berikut skrip gagal.php yang menulis galat ke stderr dan keluar dengan kode 1:

php gagal.php && echo "baris ini tidak terjalankan"

Output yang Dihasilkan:

Galat: basis data tidak dapat dihubungi.

Baris echo tidak pernah tereksekusi karena gagal.php keluar dengan 1. Ganti operatornya menjadi ||, dan shell menjalankan aksi pemulihan:

php gagal.php || echo "Menjalankan prosedur pemulihan"

Output yang Dihasilkan:

Galat: basis data tidak dapat dihubungi.
Menjalankan prosedur pemulihan

Ringkasan #

Exit code 0 menandakan sukses dan nilai lain menandakan kegagalan; tulis kode secara eksplisit dengan exit(int), jangan pernah menaruh pesan di dalam exit() karena string dicetak dan diperlakukan sebagai sukses. Galat fatal PHP keluar dengan 255, nilai disimpan modulo 256, dan operator && serta || menjadikan kode tersebut bahan baku otomasi. Dengan argumen, stream, dan exit code yang tertata, kita siap menyusun seluruhnya menjadi aplikasi console yang rapi pada chapter Console Applications.

Referensi #

• PHP Manual — exit()
• PHP Manual — Using PHP from the command line

<?php

declare(strict_types=1);

// contoh.php — rangkuman Chapter Exit Codes.
// Jalankan dengan: php contoh.php
// Memakai pola fungsi yang mengembalikan kode keluar integer.

function registrasi(int $umur): int
{
    if ($umur < 13) {
        fwrite(STDERR, "Galat: umur $umur tidak diizinkan\n");
        return 1;
    }

    echo "Registrasi diterima untuk umur $umur tahun\n";
    return 0;
}

exit(registrasi(17));