PHP extension eksikleri uygulama kurulumunda hangi hataları üretir?

Bir PHP uygulamasını kurarken hata ekranı çoğu zaman uygulamanın kendisinden değil, çalıştığı ortamın eksik hazırlanmasından kaynaklanır. Özellikle framework, e-ticaret yazılımı, panel veya özel geliştirilmiş bir proje kurulumunda gerekli PHP extension paketlerinden biri yoksa kurulum sihirbazı ilerlemez, Composer bağımlılıkları yüklenmez ya da uygulama ilk açılışta beyaz ekran verebilir. Bu nedenle hata mesajını doğru okumak, eksik modülü tahmin etmekten çok daha güvenilir bir yaklaşımdır.

PHP extension eksikliği neden kurulum hatasına dönüşür?

PHP extension, uygulamanın belirli bir işi yapabilmesi için PHP’ye eklenen modüldür. Veritabanına bağlanmak, görsel işlemek, dosya sıkıştırmak, çok dilli karakterleri düzgün yönetmek veya dış API’lere istek göndermek bu modüllerle mümkün olur. Uygulama bu yeteneklerden birini zorunlu kabul ediyorsa, ilgili extension olmadan kurulum tamamlanamaz.

Paylaşımlı hosting ortamlarında bazı extension’lar güvenlik, performans veya paket politikası nedeniyle varsayılan olarak kapalı gelebilir. VPS ya da dedicated sunucularda ise PHP sürümü kurulu olsa bile gerekli paketler ayrıca yüklenmemiş olabilir. Bu ayrım, sorunu çözerken hangi yetkiye sahip olduğunuzu anlamanızı sağlar.

Kurulumda en sık görülen hata türleri

Composer “requires ext-…” hataları

Modern PHP projelerinde en net hata Composer tarafında görülür. Örneğin ext-mbstring, ext-intl, ext-curl veya ext-zip eksikse Composer kurulumu durdurur. Mesaj genellikle şu mantıktadır: paket belirli bir PHP extension gerektiriyor ancak sistemde etkin değil.

Bu durumda yapılacak ilk işlem, hatada yazan extension adını aynen not etmektir. Paket adını yanlış yorumlamak sık yapılan bir hatadır. Örneğin ext-pdo_mysql hatası yalnızca PDO’nun değil, MySQL sürücüsünün de etkin olması gerektiğini gösterir.

Veritabanı bağlantı hataları

Uygulama kurulum ekranında “could not find driver”, “PDOException”, “mysqli extension is missing” veya “database driver not installed” gibi mesajlar görünüyorsa sorun çoğunlukla pdo_mysql, mysqli ya da ilgili veritabanı sürücüsündedir. Kullanıcı adı ve şifre doğru olsa bile sürücü yoksa bağlantı kurulamaz.

Bu noktada yalnızca veritabanı bilgilerini tekrar tekrar değiştirmek zaman kaybettirir. Önce PHP’nin hangi veritabanı sürücülerini gördüğü kontrol edilmeli, ardından uygulamanın desteklediği sürücü seçilmelidir.

Beyaz ekran, 500 hatası ve boş kurulum sayfası

Bazı eksikler açık hata mesajı üretmez; yalnızca HTTP 500, boş sayfa veya beyaz ekran olarak görünür. Özellikle mbstring, xml, fileinfo, openssl ve json gibi temel bileşenler eksik olduğunda uygulama daha hata işleme mekanizması devreye girmeden durabilir.

Bu senaryoda web sunucusu hata kayıtları incelenmelidir. PHP error log içinde “Call to undefined function”, “Class not found” veya “Unable to load dynamic library” benzeri ifadeler hangi extension’ın eksik ya da hatalı yüklendiğini gösterir.

Hangi extension hangi soruna işaret eder?

• mbstring: Türkçe karakter, çok baytlı metin işleme ve framework bağımlılıklarında kritik rol oynar.
• intl: Dil, tarih, para birimi biçimlendirme ve yerelleştirme işlemlerinde kullanılır.
• curl: Lisans doğrulama, ödeme sistemi, API entegrasyonu ve uzaktan veri çekme işlemlerinde gerekir.
• gd veya imagick: Görsel yükleme, küçük resim oluşturma ve medya işleme hatalarında kontrol edilmelidir.
• zip: Tema, eklenti, paket açma veya yedekten kurulum süreçlerinde gereklidir.
• openssl: HTTPS bağlantıları, güvenli token üretimi ve dış servis iletişiminde önemlidir.
• fileinfo: Dosya türü doğrulama ve güvenli yükleme kontrollerinde kullanılır.

Sunucuda eksik extension nasıl kontrol edilir?

Kontrol için en pratik yöntemlerden biri PHP bilgi çıktısını incelemektir. Ancak güvenlik nedeniyle bu dosya işlemden sonra silinmelidir. Komut satırı erişimi varsa aşağıdaki kontrol daha hızlı sonuç verir:

php -m

Bu komut etkin modülleri listeler. Fakat burada dikkat edilmesi gereken önemli bir nokta vardır: komut satırındaki PHP sürümü ile web sitesinin çalıştığı PHP sürümü farklı olabilir. Panel üzerinden seçilen PHP 8.2 iken terminal PHP 8.1’i gösterebilir. Bu nedenle kontrol, uygulamanın gerçekten çalıştığı PHP sürümü üzerinden yapılmalıdır.

Çözüm sürecinde yanlış yapılan noktalar

En yaygın hata, PHP sürümünü değiştirmeden yalnızca extension açmaya çalışmaktır. Bazı extension’lar belirli PHP sürümleriyle uyumlu değildir veya uygulama daha eski bir sürüm bekliyordur. Önce uygulamanın sistem gereksinimleri okunmalı, ardından PHP sürümü ve extension listesi birlikte değerlendirilmelidir.

Bir diğer risk, üretim ortamında deneme yanılma ile modül kapatıp açmaktır. Özellikle canlı çalışan sitelerde bu işlem geçici kesintilere yol açabilir. Kurulum yeni yapılacaksa hazırlık ortamında test etmek; mevcut projede işlem yapılacaksa yedek almak daha güvenli ilerleme sağlar.

Paylaşımlı hosting ve özel sunucuda yaklaşım farkı

Paylaşımlı hosting panelinde genellikle “Select PHP Version”, “PHP Extensions” veya benzeri bir bölümden modüller etkinleştirilebilir. Yetki sınırlıysa destek ekibine hatadaki extension adıyla birlikte başvurmak gerekir. “Site açılmıyor” demek yerine “PHP 8.2 için intl ve zip extension etkinleştirilebilir mi?” şeklinde net talep oluşturmak çözümü hızlandırır.

Özel sunucu tarafında paket yöneticisiyle kurulum yapılır, ardından PHP-FPM veya web sunucusu yeniden başlatılır. Burada dağıtım farkları önemlidir; Ubuntu, AlmaLinux veya Debian paket adları farklı olabilir. Ayrıca birden fazla PHP sürümü kuruluysa modülün doğru sürüme eklendiğinden emin olunmalıdır.

Kurulum öncesi kontrol listesi

Uygulamayı yüklemeden önce sistem gereksinimleri sayfasındaki PHP sürümü, zorunlu extension’lar, bellek limiti, maksimum yükleme boyutu ve veritabanı gereksinimleri kontrol edilmelidir. Composer kullanan projelerde composer check-platform-reqs komutu, eksik platform bağımlılıklarını hızlıca gösterir.

Hata mesajı net değilse kurulum günlükleri, PHP error log ve web sunucusu logları birlikte incelenmelidir. Extension eksikleri doğru tespit edildiğinde çözüm çoğu zaman karmaşık değildir; önemli olan eksik modülü, yanlış PHP sürümünü veya devre dışı sürücüyü birbirinden ayırabilmektir.