PHP "Fatal error: Uncaught Error" Çözümü: Undefined Function, Class Not Found ve Parse Error

Hata mesajını okumak: Uncaught, Stack trace, thrown in

Kılavuzun Throwable errors sayfasına göre fırlatılan bir hata, yakalanana kadar çağrı yığınında yukarı doğru ilerler. Hiçbir catch bloğu yakalamazsa ve set_exception_handler() ile bir işleyici kurulmamışsa program ölümcül hatayla sonlanır. Ekranda gördüğünüz metin, bu yolculuğun özetidir:

<?php
function siparisOlustur(array $sepet): void
{
    stokDus($sepet);
}

function stokDus(array $sepet): void
{
    throw new RuntimeException('Stok yetersiz');
}

siparisOlustur(['kalem']);
/* çıktı:
Fatal error: Uncaught RuntimeException: Stok yetersiz in /yol/ornek.php:9
Stack trace:
#0 /yol/ornek.php(4): stokDus(Array)
#1 /yol/ornek.php(12): siparisOlustur(Array)
#2 {main}
  thrown in /yol/ornek.php on line 9
*/

• Uncaught RuntimeException: yakalanmayan nesnenin sınıfı. Error görüyorsanız PHP'nin kendisi, başka bir sınıf görüyorsanız sizin ya da bir kütüphanenin kodu fırlatmıştır.
• Stok yetersiz in ...:9 hata mesajı ve fırlatıldığı dosya ile satır.
• Stack trace: en yeni çağrı en üstte olacak şekilde çağrı zinciri. #0 satırı, 4. satırda stokDus()'un çağrıldığını; #1, 12. satırda siparisOlustur()'un çağrıldığını söyler. {main} betiğin ana gövdesidir.
• thrown in ... on line 9: hatanın fırlatıldığı yerin tekrarı.

Hatanın nedeni çoğu zaman en üstteki satırda değil, zincirin biraz aşağısındadır: hatalı veriyi gönderen çağrıyı bulmak için yığın izini yukarıdan aşağıya okuyun. Kendi istisnalarınızı yazmak ve yakalamak için PHP try catch ve exception yazısına bakın.

Call to undefined function

<?php
$toplam = hesapla(10, 20);
echo $toplam, PHP_EOL;
/* çıktı:
Fatal error: Uncaught Error: Call to undefined function hesapla() in /yol/ornek.php:2
Stack trace:
#0 {main}
  thrown in /yol/ornek.php on line 2
*/

Bu hatanın beş yaygın nedeni vardır:

• Yazım hatası: fonksiyon adı yanlış yazılmış. Kılavuza göre fonksiyon adları ASCII harflerde büyük/küçük harfe duyarsız olduğu için sorun harf boyutu değil, eksik veya fazla harftir.
• Dosya dahil edilmemiş: fonksiyon başka bir dosyada tanımlı ve o dosya require edilmemiş.
• Koşullu tanım: kılavuzun User-defined functions sayfasına göre bir if bloğu içinde ya da başka bir fonksiyonun içinde tanımlanan fonksiyon, o kod çalışana kadar var olmaz.
• Eklenti yüklü değil: mb_strlen() mbstring, grapheme_strlen() intl eklentisi yüklü değilse bulunmaz. Komut satırında php -m yüklü eklentileri listeler.
• Sürüm farkı: yeni bir sürümde gelen fonksiyon eski sürümde yoktur. Örneğin array_find() PHP 8.4, array_first() PHP 8.5 ile geldi; bu kodlar daha eski bir sunucuda bu hatayı verir (PHP 8.4 yenilikleri, PHP 8.5 yenilikleri).

Namespace kullanan bir dosyada çağrılan fonksiyon önce o namespace içinde aranır, bulunamazsa genel alana düşülür. Kendi fonksiyonunuzu başka bir namespace içinde tanımladıysanız onu tam adıyla ya da use function ile içe aktararak çağırmanız gerekir: PHP namespace ve use. Fonksiyonun var olup olmadığını çalışma anında kontrol etmek için function_exists(), sınıflar için class_exists(), metotlar için method_exists() kullanılır:

<?php
if (!function_exists('selam')) {
    function selam(): string { return 'Merhaba'; }
}
var_dump(function_exists('selam'), class_exists('Sepet'), method_exists('DateTime', 'format'));
echo selam(), PHP_EOL;
/* çıktı:
bool(true)
bool(false)
bool(true)
Merhaba
*/

Call to undefined method ve Call to a member function on null

Nesne üzerinde sınıfta tanımlı olmayan bir metodu çağırırsanız mesaj sınıf adını ve metodu birlikte verir. Daha sık görülen ikinci mesaj ise metodun çağrıldığı değişkenin aslında bir nesne olmadığını, çoğu zaman null olduğunu söyler.

<?php
class Sepet
{
    public function ekle(string $urun): void {}
}

$s = new Sepet();
$s->sil('kalem');
/* çıktı:
Fatal error: Uncaught Error: Call to undefined method Sepet::sil() in /yol/ornek.php:8
Stack trace:
#0 {main}
  thrown in /yol/ornek.php on line 8
*/

<?php
function kullaniciBul(int $id): ?Kullanici
{
    return null;
}

$k = kullaniciBul(7);
echo $k->adGetir();
/* çıktı:
Fatal error: Uncaught Error: Call to a member function adGetir() on null in /yol/ornek.php:8
Stack trace:
#0 {main}
  thrown in /yol/ornek.php on line 8
*/

"on null" kısmı, değişkenin değerinin tipini söyler; aynı mesajı "on false", "on array" veya "on string" olarak da görebilirsiniz. Tipik senaryo, bulunamayan bir kayıt için null döndüren bir arama fonksiyonudur. Çözüm, sonucu kullanmadan önce kontrol etmektir: if ($k === null) { ... }. Değer gerçekten isteğe bağlıysa nullsafe operatörü $k?->adGetir() hata yerine null döndürür. Dönüş tipindeki ?Kullanici işareti de size bu ihtimali önceden haber verir.

Benzer bir mesaj, nesne olmayan bir değere özellik yazmaya çalıştığınızda çıkar. PHP 8.0 öncesinde bazı durumlarda sessizce stdClass nesnesi oluşturulurdu; PHP 8.0 Backward Incompatible Changes sayfasına göre bu artık bir Error:

<?php
$x = 5;
$x->deger = 1;
/* çıktı:
Fatal error: Uncaught Error: Attempt to assign property "deger" on int in /yol/ornek.php:3
Stack trace:
#0 {main}
  thrown in /yol/ornek.php on line 3
*/

Class "X" not found

<?php
$fatura = new Fatura();
/* çıktı:
Fatal error: Uncaught Error: Class "Fatura" not found in /yol/ornek.php:2
Stack trace:
#0 {main}
  thrown in /yol/ornek.php on line 2
*/

Sınıf bulunamıyorsa üç yere bakın. Birincisi, sınıfın tanımlandığı dosya dahil edilmiş mi ya da bir autoloader bu dosyayı bulabiliyor mu? İkincisi, namespace doğru mu? App\Model içindeki Fatura sınıfını başka bir dosyada kullanıyorsanız use App\Model\Fatura; satırı gerekir. Üçüncüsü, dosya adı ve klasör yapısı autoloader'ın beklediği kurala uyuyor mu; sınıf adındaki tek bir harf farkı bile dosyanın bulunamamasına yol açabilir. Otomatik yükleme spl_autoload_register, ad alanları namespace ve use yazısında anlatılıyor.

Yakın akraba iki mesaj daha var: interface ya da abstract sınıftan doğrudan nesne üretmeye çalışmak. Bu yapılar yalnızca başka sınıflara şablon olur; somut bir alt sınıf yazıp onu örneklemelisiniz (kalıtım, abstract ve interface).

<?php
interface Odeme {}
abstract class Temel {}
foreach (['Odeme', 'Temel'] as $sinif) {
    try {
        new $sinif();
    } catch (Error $e) {
        echo $e->getMessage(), PHP_EOL;
    }
}
/* çıktı:
Cannot instantiate interface Odeme
Cannot instantiate abstract class Temel
*/

Undefined constant

Tanımsız bir sabit kullanmak PHP 8.0'dan beri Error fırlatır. Kılavuzun PHP 8.0 uyumsuzluk listesine göre eskiden tırnaksız tanımsız sabit adı yalnızca uyarı üretir ve metin olarak yorumlanırdı. Bu yüzden eski kodlarda sık görülen tırnaksız dizi anahtarı ($ayar[ad]) artık betiği durdurur:

<?php
$ayar = ['ad' => 'Site'];
echo $ayar[ad], PHP_EOL;
/* çıktı:
Fatal error: Uncaught Error: Undefined constant "ad" in /yol/ornek.php:3
Stack trace:
#0 {main}
  thrown in /yol/ornek.php on line 3
*/

Çözüm anahtarı tırnağa almaktır: $ayar['ad']. Gerçekten bir sabit kullanıyorsanız define() veya const tanımının çağrıdan önce çalıştığından ve namespace içinde doğru adla arandığından emin olun. Sabitlerin tanımlanması PHP sabitler: define ve const yazısında.

Cannot redeclare function

Kılavuza göre PHP fonksiyon aşırı yüklemeyi (overloading) desteklemez ve tanımlanmış bir fonksiyon yeniden tanımlanamaz. Aynı adlı ikinci bir tanım derleme aşamasında ölümcül hata verir. Bu hata "Uncaught" içermez, çünkü yakalanabilen bir istisna değildir.

<?php
function selam(): string { return 'Merhaba'; }
function selam(): string { return 'Selam'; }
/* çıktı:
Fatal error: Cannot redeclare function selam() (previously declared in /yol/ornek.php:2) in /yol/ornek.php on line 3
Stack trace:
#0 {main}
*/

Tek dosyada bu hatayı fark etmek kolaydır. Asıl zor olan, aynı fonksiyon dosyasının iki kez dahil edilmesidir; bu, büyük projelerde farklı dosyaların aynı yardımcı dosyayı require etmesiyle olur:

<?php
require 'inc/yardimci.php';
require 'inc/yardimci.php';
echo paraBicimle(1250.5), PHP_EOL;
/* çıktı:
Fatal error: Cannot redeclare function paraBicimle() (previously declared in /yol/inc/yardimci.php:2) in /yol/inc/yardimci.php on line 2
Stack trace:
#0 {main}
*/

Mesajın iki kez aynı dosyayı ve satırı göstermesi, ipucunun ta kendisidir: fonksiyon iki farklı yerde değil, aynı yerde iki kez tanımlanmaya çalışılmış. include_once ve require_once, bir dosya zaten dahil edildiyse onu tekrar yüklemez. Kılavuz bu yapıları özellikle fonksiyonların yeniden tanımlanması gibi sorunları önlemek için önerir. Örnekteki inc/yardimci.php dosyası number_format() ile para biçimlendiren tek bir fonksiyon içeriyor:

<?php
require_once 'inc/yardimci.php';
require_once 'inc/yardimci.php';
echo paraBicimle(1250.5), PHP_EOL; // çıktı: 1.250,50 TL

Bir başka neden de PHP sürümü yükseltmesidir. Kılavuzun PHP 8.4 uyumsuzluk sayfası, her yeni fonksiyonun, sınıfın veya sabitin yeniden bildirim hatasına yol açabileceğini hatırlatır. Projenizde önceden array_find veya mb_trim adlı kendi fonksiyonunuz varsa, PHP 8.4'e geçtiğinizde bu hatayı alırsınız. Çözüm ya kendi fonksiyonunuzu function_exists() kontrolüyle sarmak ya da ona başka bir ad vermek, en iyisi de kendi kodunuzu bir namespace içine almaktır.

Failed opening required: dosya bulunamadı

require sayfasına göre require, include ile aynıdır; tek farkı, dosya bulunamazsa uyarının yanında bir Error da fırlatmasıdır (PHP 8.0 öncesinde E_COMPILE_ERROR). include ise yalnızca uyarı verip devam eder:

<?php
require 'inc/olmayan.php';
echo 'devam', PHP_EOL;
/* çıktı:
Warning: require(inc/olmayan.php): Failed to open stream: No such file or directory in /yol/ornek.php on line 2

Fatal error: Uncaught Error: Failed opening required 'inc/olmayan.php' (include_path='.;C:\php\pear') in /yol/ornek.php:2
Stack trace:
#0 {main}
  thrown in /yol/ornek.php on line 2
*/

<?php
include 'inc/olmayan.php';
echo 'include sonrası devam', PHP_EOL;
/* çıktı:
Warning: include(inc/olmayan.php): Failed to open stream: No such file or directory in /yol/ornek.php on line 2

Warning: include(): Failed opening 'inc/olmayan.php' for inclusion (include_path='.;C:\php\pear') in /yol/ornek.php on line 2
include sonrası devam
*/

Parantez içindeki include_path değeri sisteme göre değişir (yukarıdaki Windows'ta çalışan yapılandırmasız CLI'nın değeri). Bu hatanın en yaygın nedeni göreli yoldur: include sayfasına göre yol verilmezse dosya önce include_path'te, sonra çağıran betiğin klasöründe ve çalışma dizininde aranır; ./ veya ../ ile başlayan yollar ise doğrudan çalışma dizinine göre çözülür. Çalışma dizini, betiği komut satırından mı yoksa web sunucusundan mı çalıştırdığınıza göre değişebilir. Bu belirsizliği ortadan kaldırmanın yolu, yolu __DIR__ sihirli sabitiyle mutlak hâle getirmektir: require __DIR__ . '/inc/yardimci.php';.

Parse error: syntax error, unexpected

Ayrıştırma hatası, PHP'nin kodunuzu okuyamadığı anlamına gelir; dosyadaki tek bir satır bile çalışmaz. En sık nedenler eksik noktalı virgül, kapanmamış parantez veya süslü parantez ve kapanmamış tırnaktır. Önemli bir ipucu: PHP hatayı, sorunun fark edildiği satırda bildirir. Eksik noktalı virgül çoğu zaman bir sonraki satırda raporlanır:

<?php
$ad = 'Deniz'
echo "Merhaba $ad", PHP_EOL;
/* çıktı:
Parse error: syntax error, unexpected token "echo" in /yol/ornek.php on line 3
*/

<?php
if (true) {
    echo 'açık blok', PHP_EOL;

Parse error: Unclosed '{' on line 2 in /yol/ornek.php on line 4

İlk örnekte hata 2. satırdadır ama mesaj 3. satırı gösterir; PHP echo kelimesini görünce önceki ifadenin bitmediğini anlar. İkinci mesaj daha yardımseverdir: açılan süslü parantezin satırını (on line 2) ve dosyanın bittiği satırı birlikte verir. Kodu çalıştırmadan denetlemek için php -l dosya.php komutunu kullanın; ayrıntılar PHP CLI yazısında, temel sözdizimi kuralları PHP temel sözdizimi yazısında.

Kılavuzun ParseError sayfasına göre ParseError, CompileError sınıfından türeyen bir hatadır. Hatalı dosyanın kendisi içinde yakalanamaz, çünkü dosya hiç derlenmez. Ancak başka bir dosyayı require ederken ya da eval() ile kod çalıştırırken oluşan ayrıştırma hatasını çağıran taraf yakalayabilir:

<?php
try {
    require __DIR__ . '/inc/bozuk.php';
} catch (ParseError $e) {
    echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    echo basename($e->getFile()), ' satır ', $e->getLine(), PHP_EOL;
}
echo 'ana betik devam ediyor', PHP_EOL;
/* çıktı:
ParseError: syntax error, unexpected token "}", expecting ";"
bozuk.php satır 4
ana betik devam ediyor
*/

Buradaki inc/bozuk.php dosyasında return 1 satırının sonundaki noktalı virgül eksik; hata yine bir sonraki satırda, kapanan süslü parantezde raporlandı. 8.5 sözdizimiyle (pipe operatörü |> gibi) yazılmış kodu daha eski bir PHP sürümünde çalıştırmak da aynı türden bir ayrıştırma hatası üretir.

Yakalanmayan hatalar için genel işleyici

Üretim ortamında kullanıcıya PHP'nin ham hata metnini göstermek istemezsiniz. set_exception_handler ile kaydedilen işleyici, yakalanmayan her Throwable için çağrılır. Kılavuz bunun kodun tamamını bir try/catch ile sarmaya benzediğini, ama işleyici döndükten sonra betiğin sonlandığını belirtir:

<?php
set_exception_handler(function (Throwable $e): void {
    echo 'Beklenmeyen hata: ', get_class($e), ' - ', $e->getMessage(), PHP_EOL;
});

echo 'Başladı', PHP_EOL;
tanimsizFonksiyon();
echo 'Bu satır çalışmaz', PHP_EOL;
/* çıktı:
Başladı
Beklenmeyen hata: Error - Call to undefined function tanimsizFonksiyon()
*/

Gerçek bir uygulamada işleyici hatayı ayrıntılarıyla günlüğe yazar, ziyaretçiye ise genel bir hata sayfası gösterir. Parse error ve Cannot redeclare gibi derleme hataları bu işleyiciye ulaşmaz, çünkü işleyiciyi kaydeden kod bile çalışmaz. Hata gösterimi ve raporlama seviyeleri için PHP error_reporting ve hata seviyeleri yazısına bakın.

Sık yapılan hatalar

• Hata mesajındaki satıra bakıp orada sorun bulamamak: ayrıştırma hatalarında bir önceki satıra, "on null" hatalarında değişkenin değerini atayan satıra bakın.
• catch (Exception $e) ile Error türündeki hataları yakalamayı beklemek; ikisini birden yakalamak için Throwable kullanın.
• require ile göreli yol kullanıp betiği farklı klasörden çalıştırınca dosyayı bulamamak; __DIR__ kullanın.
• Fonksiyon dosyalarını require ile birden fazla yerde yüklemek; require_once veya autoload kullanın.
• Yerelde yeni PHP sürümüyle yazılan kodu eski sürümlü sunucuya göndermek; php -v ile iki ortamın sürümünü karşılaştırın.

Sık Sorulan Sorular

"Fatal error" ile "Fatal error: Uncaught" arasında fark var mı?

Evet. "Uncaught" içeren mesajlar yakalanabilir bir Throwable'dan gelir; kodunuzu uygun bir try/catch ile sararsanız betik devam edebilir. "Uncaught" içermeyen "Cannot redeclare" veya çalışma süresi aşımı gibi ölümcül hatalar ise yakalanamaz.

Beyaz sayfa görüyorum ama hata mesajı yok, neden?

Büyük olasılıkla hata gösterimi kapalıdır ve mesaj yalnızca günlüğe yazılıyordur. Kılavuz üretimde display_errors ayarının kapalı, log_errors ayarının açık olmasını önerir. Mesajı görmek için sunucunun hata günlüğüne bakın ya da betiği komut satırından çalıştırın.

ParseError'ı kendi dosyamın içinde yakalayabilir miyim?

Hayır. Dosya ayrıştırılamadığı için içindeki try bloğu da çalışmaz. Yalnızca başka bir dosyayı dahil eden ya da eval() çağıran kod, oluşan ParseError'ı yakalayabilir.

Hata WordPress sitemde çıkıyor, nereden başlamalıyım?

Mesajdaki dosya yolu hatanın hangi eklentiden veya temadan geldiğini söyler. Sorun çoğu zaman eklentinin, sunucunuzdaki PHP sürümünde bulunmayan ya da artık kaldırılmış bir fonksiyonu kullanmasıdır. Sürüm uyumu için WordPress PHP sürümü yükseltme yazısına bakabilirsiniz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: PHP öğrenme rehberi · try catch ve exception · TypeError hataları · Undefined variable uyarısı · Autoload · PHP CLI