İçeriğe geç
Çılgın Yazılım

Geliştirici Araçları kod örnekli

PHP GD Extension Nasıl Etkinleştirilir? XAMPP, Linux ve Docker

Eklentiyi açtınız, Apache'yi yeniden başlattınız, Composer hâlâ GD yok diyor. Böyle bir durumda ilk bakılacak yer eklenti değil, düzenlediğiniz php.ini dosyasıdır.

Çılgın Yazılım 5 dk okuma

PHP GD Extension Nasıl Etkinleştirilir? XAMPP, Linux ve Docker
İçindekiler
  1. Adım 1: PHP'nin hangi php.ini dosyasını okuduğunu bulun
  2. Adım 2: XAMPP ve Windows'ta eklentiyi açın
  3. Adım 3: Linux'ta paketi kurun
  4. Adım 4: Docker imajında derleyin
  5. Composer ext-gd hatası: kontrolü susturmayın
  6. Test etmek: eklenti gerçekten yüklendi mi?

PHP GD extension, PHP'nin görsel oluşturma ve işleme eklentisidir: küçük resim üretmek, görseli WebP'ye çevirmek ya da PDF'e resim gömmek gibi işler ona dayanır. Windows ve XAMPP'te php.ini dosyasındaki ;extension=gd satırını açıp Apache'yi yeniden başlatmak, Debian ve Ubuntu'da php8.2-gd gibi sürümlü paketi kurmak, Docker'da ise eklentiyi bağımlılıklarıyla derlemek yeterlidir. Oysa en çok zaman kaybettiren adım bunlar değil, yanlış php.ini dosyasını düzenlemektir.

Eklenti kapalıyken hata genellikle başka bir yerden gelir: Composer "ext-gd" der, dompdf gibi kütüphaneler "the PHP GD extension is required" diye durur.

PHP GD eklentisinin yüklendiğini doğrulamak için kontrol sırası
İlk soru eklentinin varlığı değil, hangi php.ini dosyasının okunduğudur.

Adım 1: PHP'nin hangi php.ini dosyasını okuduğunu bulun

Bir şeyi değiştirmeden önce, çalışan PHP'nin gerçekten hangi dosyayı okuduğunu öğrenin. Komut satırında bunu tek komut söyler:

Bash
php --ini
# Loaded Configuration File:         C:\xampp\php\php.ini

Dikkat: bu, komut satırındaki PHP'nin dosyasıdır; web sunucusu başka bir dosya okuyor olabilir.

XAMPP'te Apache, httpd-xampp.conf içindeki PHPINIDir satırıyla aynı klasörü gösterir, yani iki taraf aynı dosyayı paylaşır. Debian ve Ubuntu'da ise komut satırı, Apache modülü ve PHP-FPM için ayrı dosyalar vardır: /etc/php/8.2/cli/php.ini, /etc/php/8.2/apache2/php.ini ve /etc/php/8.2/fpm/php.ini. "Tarayıcıda çalışıyor, Composer'da çalışmıyor" durumunun arkasında çoğu zaman bu ayrım vardır.

Adım 2: XAMPP ve Windows'ta eklentiyi açın

Windows'ta GD, PHP ile birlikte gelen php_gd.dll dosyasıdır; kurmanız gerekmez, yalnız açmanız gerekir. php.ini dosyasında satırı bulup başındaki noktalı virgülü kaldırın:

INI
; Önce: kapalı
;extension=gd

; Sonra: açık (PHP 8.0 ve sonrası)
extension=gd

PHP 8.0'dan eski sürümlerde dosyanın adı php_gd2.dll, satır da extension=gd2 idi. Eski bir rehberdeki satırı PHP 8'e kopyalarsanız eklenti yüklenmez ve PHP açılışta "Unable to load dynamic library" uyarısı verir; bu tür uyarıların diğer nedenleri için PHP hata mesajları ve hızlı çözümleri yazısına bakabilirsiniz.

Kaydettikten sonra XAMPP Kontrol Paneli'nden Apache'yi durdurup yeniden başlatın. Komut satırındaki PHP ise dosyayı her çalıştırmada yeniden okur.

Adım 3: Linux'ta paketi kurun

Linux dağıtımlarında GD ayrı bir paket olarak gelir. Paket adındaki sürüm, çalışan PHP'nin sürümüyle aynı olmalıdır:

Bash
php -v                                # ör. PHP 8.2.x
sudo apt install php8.2-gd            # Debian / Ubuntu
sudo systemctl restart php8.2-fpm     # Apache modülü kullanıyorsanız: apache2
ls /etc/php/8.2/*/conf.d/ | grep gd   # her ortamda 20-gd.ini görünmeli
# RHEL, Rocky, AlmaLinux: sudo dnf install php-gd

Debian ve Ubuntu paketi eklentiyi komut satırı dahil bütün PHP ortamlarında kendisi açar; son komut bunu doğrular. Sunucuda birden fazla PHP sürümü kuruluysa sürüm numarasız php-gd paketi varsayılan sürüme kurulur; siteniz başka bir sürümde çalışıyorsa hiçbir şey değişmez.

Adım 4: Docker imajında derleyin

Resmî php Docker imajlarında GD kaynak koddan derlenir ve görsel biçimlerinin kütüphaneleri ayrıca kurulur. WebP desteği de istiyorsanız resmî örneğe libwebp-dev paketini ve --with-webp seçeneğini ekleyin:

Dockerfile
FROM php:8.2-fpm
RUN apt-get update && apt-get install -y \
        libfreetype-dev libjpeg62-turbo-dev libpng-dev libwebp-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
    && docker-php-ext-install -j$(nproc) gd \
    && rm -rf /var/lib/apt/lists/*

Dikkat: bağımlılıkları kurmadan yalnız docker-php-ext-install gd yazarsanız eklenti ya hiç derlenmez ya da JPEG ve WebP desteği olmadan derlenir; bunu test adımında görürsünüz. Son satır apt paket listelerini aynı katmanda siler; imajı küçültmenin diğer yolları için katman katman küçültme yazısına bakabilirsiniz.

Composer ext-gd hatası: kontrolü susturmayın

Projeniz GD'ye bağlı bir paket kullanıyorsa ve komut satırındaki PHP'de eklenti yoksa Composer kurulumu durdurur. composer.lock dosyası varken çıktı şöyledir:

Bash
$ composer install
Installing dependencies from lock file (including require-dev)
Verifying lock file contents can be installed on current platform.
Your lock file does not contain a compatible set of packages. Please run composer update.

  Problem 1
    - Root composer.json requires PHP extension ext-gd * but it is missing from your system. Install or enable PHP's gd extension.

Lock dosyası yoksa ilk satır "Your requirements could not be resolved to an installable set of packages." olur; GD'yi bir bağımlılık istiyorsa satırda o paketin adı yazar. Mesajın önerdiği composer update sorunu çözmez, çünkü eksik olan paket değil eklentidir.

--ignore-platform-req=ext-gd seçeneği de kurulumu geçirir ama eklentiyi yüklemez; kod ilk görsel işleminde çalışma anında hata verir. Bu seçenek yalnız kurulumu GD'siz bir makinede yapıp kodu GD'li başka bir ortamda çalıştıracaksanız anlamlıdır. Doğru çözüm, Adım 1'de bulduğunuz dosyada eklentiyi açmaktır.

Test etmek: eklenti gerçekten yüklendi mi?

Komut satırında iki kontrol yeter: eklenti listede mi ve beklediğiniz biçimleri destekliyor mu?

Bash
php -m | grep -i gd            # Windows: php -m | findstr /i gd
php -r "var_dump(extension_loaded('gd'), function_exists('gd_info') && (gd_info()['WebP Support'] ?? false));"
# GD ve WebP açıksa: bool(true) bool(true)
# GD yoksa:          bool(false) bool(false)

Web tarafı için geçici bir PHP dosyasına var_dump(extension_loaded('gd'), php_ini_loaded_file()); yazıp tarayıcıda açın: ilk değer eklentinin yüklendiğini, ikincisi web tarafının hangi php.ini dosyasını okuduğunu gösterir. CodeIgniter 4'ün görsel servisi varsayılan olarak GD sürücüsünü kullanır (Config\Images::$defaultHandler değeri gd); service('image') ile bir küçük resim üretebiliyorsanız web tarafı da hazırdır.

GD görseli işlerken bellekte sıkıştırılmamış hâlde tutar ve kabaca genişlik × yükseklik × 4 bayt yer kaplar: 10.000 × 10.000 piksellik bir görsel yaklaşık 400 MB demektir ve varsayılan 128 MB'lık memory_limit değerini aşar. Kullanıcıdan gelen görselin boyutunu işlemeden önce getimagesize() ile kontrol edin; yükleme ucunun geri kalanı için CodeIgniter'da güvenli dosya yükleme yazısına bakın.

Aynı kontrol için sık önerilen phpinfo() sayfası ortam değişkenlerini düz metin gösterir: Docker'da -e DB_PASSWORD=… ile verilen bir parola da orada görünür. Hangi yöntemi seçerseniz seçin, kontrol dosyasını iş bitince silin; canlı sunucuda bırakmayın.

GD kurulumundaki asıl tuzak eklentinin yokluğu değil, düzenlenen php.ini dosyasının PHP'nin okuduğu dosya olmamasıdır. Önce php --ini ile okunan php.ini dosyasını bulun, Windows'ta extension=gd satırını açın, Linux'ta PHP sürümünüzle aynı paketi kurun, Docker'da bağımlılıklarıyla derleyin ve her değişiklikten sonra hem komut satırını hem web tarafını test edin. Composer kontrolünü susturmak yerine eklentiyi açın; ekipte herkesin aynı eklentilerle çalışması için yerel geliştirme ortamını tek komutla kurmak iyi bir sonraki adımdır.

Konunun derinlemesine anlatımı için: PHP Kılavuzu — GD Installation.

Beğeniniz benzer içerikleri öne çıkarmamıza yardımcı olur.

Sık sorulan sorular

GD mi Imagick mi kullanmalıyım?

Çoğu web işi için GD yeter; Windows derlemelerinde PHP ile gelir, Linux'ta ayrı paket olarak kurulur. Imagick daha fazla biçim ve daha gelişmiş işlem sunar, ama sunucuya ImageMagick kurulmasını gerektirir. Kütüphaneniz ikisini de destekliyorsa kurulu olanı seçin.

Eklentiyi açtım ama phpinfo() hâlâ göstermiyor, neden?

Büyük olasılıkla web sunucusu yeniden başlatılmadı ya da düzenlediğiniz dosya web tarafının okuduğu dosya değil. phpinfo() çıktısının başındaki "Loaded Configuration File" satırı, web tarafının gerçekten hangi dosyayı okuduğunu gösterir.

gd_info() WebP desteği için neden false dönüyor?

GD, derlenirken WebP kütüphanesi olmadan kurulmuş. XAMPP 8.2 ile gelen hazır DLL'de destek açıktır. Docker'da libwebp-dev paketini kurup gd'yi --with-webp seçeneğiyle yeniden derlemeniz gerekir.

Paylaşımlı hostingde GD'yi nasıl açarım?

php.ini dosyasına erişiminiz yoksa kontrol panelindeki PHP ayarlarından eklenti listesinde gd'yi işaretleyin; CloudLinux kullanan birçok cPanel sunucusunda bu ekranın adı "Select PHP Version"dır. Bu seçenek yoksa barındırma firmasından açmasını isteyin.

Yazan

Çılgın Yazılım

Ben Evren Çılgın; yazılım geliştirme, web teknolojileri ve sistem tasarımı alanlarında uzmanlaşmış bir geliştiriciyim. Uzun yıllardır hem frontend hem de backend tarafında üretken, ölçeklenebilir ve kullanıcı dostu çözümler üretiyorum.

Hakkımızda Bize ulaşın

Bu konuda bir projeniz mi var?

İhtiyacınızı birkaç cümleyle anlatın; uygun yaklaşımı birlikte belirleyelim.

Projenizi Anlatın

İlgili yazılar

Yorumlar

Henüz yorum yok. Sorunuzu ya da deneyiminizi ilk siz yazın.

Yorum yazın

Yorumunuz onaylandıktan sonra yayınlanır. Ekibimiz gerekirse konuyla ilgili bir yanıt da paylaşır.

Yayınlanmaz; yalnızca gerektiğinde size ulaşmak için.

En az 10 karakter.

Tüm yazılar