PHP Eklentisi Kurulumu: mbstring, curl ve zip

Yazar:komut.io ekibi PHP Sürüm Yönetimi ve Yapılandırma
0 Yorum

PHP uygulamaları geliştirirken ya da bir sunucuya yeni bir proje deploy ederken en sık karşılaşılan sorunlardan biri eksik PHP eklentileridir. Composer çalıştırıyorsunuz, birden mbstring extension is missing hatası. Laravel kuruyorsunuz, cURL extension is not loaded diyor. ZIP arşivleriyle çalışacaksınız, zip extension not found. Bu yazıda bu üç kritik eklentiyi, neden gerekli olduklarını, nasıl kurulacaklarını ve yapılandırılacaklarını gerçek dünya senaryolarıyla ele alacağız.

mbstring, curl ve zip Neden Bu Kadar Önemli?

Bu üç eklenti, modern PHP uygulamalarının neredeyse tamamında kullanılmaktadır. Popüler framework ve araçların büyük çoğunluğu bu eklentileri zorunlu bağımlılık olarak listeler.

mbstring (Multibyte String): Türkçe, Japonca, Arapça gibi çok baytlı karakter setleriyle çalışmak için şarttır. strlen() fonksiyonu ASCII karakterlerde düzgün çalışır ama “Güneş” kelimesinin uzunluğunu hesaplarken hata yapabilir. mbstring bu sorunu çözer.

curl: HTTP istekleri göndermek, API’larla iletişim kurmak, dosya indirmek için kullanılır. Composer bile curl olmadan düzgün çalışmaz. Ödeme sistemleri entegrasyonları, OAuth akışları, webhook’lar hepsi curl’e bağımlıdır.

zip: ZIP arşivi oluşturma ve açma işlemleri için gereklidir. WordPress eklenti güncellemeleri, yedekleme sistemleri, dosya yükleme ve paketleme işlemleri bu eklentiyi kullanır.

Mevcut PHP Kurulumunu Kontrol Etme

Önce neyin kurulu olup olmadığını görelim. Sunucuya bağlandığınızda ilk yapmanız gereken şey budur.

# PHP sürümünü kontrol et
php -v

# Yüklü tüm eklentileri listele
php -m

# Belirli bir eklentinin yüklü olup olmadığını kontrol et
php -m | grep -E "mbstring|curl|zip"

# PHP bilgilerini detaylı görmek için
php -i | grep -E "mbstring|curl|zip"

Eğer bu komutlardan sonra ilgili eklentileri göremiyorsanız kurulum gerekiyor demektir. Web tabanlı kontrol için de şunu kullanabilirsiniz:

# Geçici bir test dosyası oluştur
echo "<?php phpinfo(); ?>" > /tmp/phpinfo.php
php /tmp/phpinfo.php | grep -E "mbstring|curl|zip"
# Test sonrası dosyayı sil
rm /tmp/phpinfo.php

Ubuntu/Debian Tabanlı Sistemlerde Kurulum

Ubuntu ve Debian tabanlı dağıtımlarda apt paket yöneticisini kullanıyoruz. PHP sürümüne göre paket isimleri değiştiği için dikkatli olmak gerekiyor.

PHP Sürümünü Belirleme ve Repo Ekleme

# Mevcut PHP sürümünü öğren
php -r "echo PHP_VERSION;"

# Eğer PHP 8.x kullanmak istiyorsanız ve henüz kurulu değilse
# Ondrej PPA ekleyin (Ubuntu için)
sudo add-apt-repository ppa:ondrej/php
sudo apt update

Eklenti Kurulumu

# PHP 8.2 için örnek (sürüm numarasını değiştirin)
sudo apt install php8.2-mbstring php8.2-curl php8.2-zip

# Eğer sürüm belirtmeden kurmak istiyorsanız
# (varsayılan PHP için)
sudo apt install php-mbstring php-curl php-zip

# Birden fazla sürüm varsa hepsini birden kurmak için
sudo apt install php7.4-mbstring php7.4-curl php7.4-zip 
                 php8.1-mbstring php8.1-curl php8.1-zip 
                 php8.2-mbstring php8.2-curl php8.2-zip

Kurulum sonrası web sunucusunu yeniden başlatmak zorunludur. PHP-FPM kullanıyorsanız sadece FPM servisini restart etmek yeterlidir, Apache veya Nginx’i yeniden başlatmak gerekmez ama emin olmak için her ikisini de yapabilirsiniz.

# Apache ile çalışıyorsanız
sudo systemctl restart apache2

# Nginx + PHP-FPM kullanıyorsanız
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

# Servislerin durumunu kontrol et
sudo systemctl status php8.2-fpm

CentOS/RHEL/AlmaLinux/Rocky Linux Sistemlerde Kurulum

Red Hat tabanlı sistemlerde işler biraz farklı işliyor. Özellikle CentOS 7 ile AlmaLinux 8/9 arasında farklılıklar var.

# EPEL ve Remi repo'larını ekle (RHEL/CentOS 7 için)
sudo yum install epel-release
sudo yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm

# AlmaLinux 8/9 veya RHEL 8/9 için
sudo dnf install epel-release
sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-8.rpm

# Remi reposundan PHP 8.2 modülünü etkinleştir
sudo dnf module enable php:remi-8.2

# Eklentileri kur
sudo dnf install php-mbstring php-curl php-zip

# Servisi yeniden başlat
sudo systemctl restart php-fpm
sudo systemctl restart httpd

Arch Linux / Manjaro Sistemlerde Kurulum

# Arch Linux'ta PHP eklentileri genellikle php-* paketleri şeklinde gelir
sudo pacman -S php-intl

# curl ve zip çoğunlukla php paketiyle birlikte gelir
# ama eksikse
sudo pacman -S php

# php.ini üzerinden eklentileri etkinleştir
sudo nano /etc/php/php.ini
# extension=curl, extension=zip satırlarının başındaki ; işaretini kaldır

php.ini Üzerinden Manuel Etkinleştirme

Bazen eklenti kurulu olmasına rağmen php.ini içinde devre dışı bırakılmış olabilir. Bu durumu sıkça sunucu göçlerinde ve özelleştirilmiş Docker imajlarında görürsünüz.

# php.ini dosyasının nerede olduğunu bul
php --ini

# Genellikle şu konumlarda bulunur:
# /etc/php/8.2/cli/php.ini (CLI için)
# /etc/php/8.2/fpm/php.ini (FPM için)
# /etc/php/8.2/apache2/php.ini (Apache için)

# Eklenti durumunu kontrol et
grep -E "^;?extension=(mbstring|curl|zip)" /etc/php/8.2/fpm/php.ini

Eğer satırın başında ; varsa yorum satırı olarak işaretlenmiş demektir ve eklenti devre dışıdır.

# Sed ile otomatik olarak etkinleştir
sudo sed -i 's/^;extension=mbstring/extension=mbstring/' /etc/php/8.2/fpm/php.ini
sudo sed -i 's/^;extension=curl/extension=curl/' /etc/php/8.2/fpm/php.ini
sudo sed -i 's/^;extension=zip/extension=zip/' /etc/php/8.2/fpm/php.ini

# Değişikliği doğrula
grep -E "^extension=(mbstring|curl|zip)" /etc/php/8.2/fpm/php.ini

Bazı sistemlerde eklentiler ayrı .ini dosyalarında yönetilir. Ubuntu/Debian’da /etc/php/8.2/mods-available/ dizininde bu dosyaları görebilirsiniz ve phpenmod komutuyla etkinleştirebilirsiniz:

# Eklentiyi etkinleştir
sudo phpenmod mbstring curl zip

# Devre dışı bırakmak için
sudo phpdismod mbstring

# Hangi eklentilerin aktif olduğunu gör
ls /etc/php/8.2/fpm/conf.d/

Docker Ortamında PHP Eklentisi Kurulumu

Günümüzde birçok proje Docker üzerinde çalışıyor. Docker imajlarında PHP eklentilerini kurmak biraz farklı bir yaklaşım gerektiriyor.

FROM php:8.2-fpm

# Sistem bağımlılıklarını kur
RUN apt-get update && apt-get install -y 
    libzip-dev 
    libcurl4-openssl-dev 
    && rm -rf /var/lib/apt/lists/*

# PHP eklentilerini kur
# mbstring PHP 8.x ile birlikte geliyor, ayrıca kurmak gerekmeyebilir
RUN docker-php-ext-install mbstring curl zip

# Kurulumu doğrula
RUN php -m | grep -E "mbstring|curl|zip"

Eğer docker-php-ext-install yetersiz kalıyorsa pecl ile de kurulum yapabilirsiniz:

# Dockerfile içinde veya container içinde
RUN pecl install zip && docker-php-ext-enable zip

Docker Compose kullananlar için compose dosyasında build context tanımlayarak bu Dockerfile’ı kullanabilirsiniz. Özellikle ekip ortamında herkesin aynı eklentilerle çalışması için bu yaklaşım son derece değerlidir.

Gerçek Dünya Senaryosu 1: Laravel Kurulumu Sırasında Karşılaşılan Hatalar

Yeni bir sunucuya Laravel projesi kurarken bu eklentiler olmadan şu hataları alırsınız:

PHP Extension mbstring is missing from your system. Please install or enable it.
The requested PHP extension curl is missing from your system.

Composer ile kurulum yaparken bile hata alabilirsiniz:

# Hatalı durumda composer çalıştırıldığında
composer create-project laravel/laravel myapp
# HATA: mbstring extension is missing

# Doğru yaklaşım: Önce eklentileri kur, sonra composer çalıştır
sudo apt install php8.2-mbstring php8.2-curl php8.2-zip php8.2-xml
sudo systemctl restart php8.2-fpm

# Şimdi composer çalıştır
composer create-project laravel/laravel myapp

# Laravel'in gereksinimlerini kontrol et
cd myapp
php artisan --version

Bu senaryoda zip eklentisi de önemlidir çünkü Composer bağımlılıkları ZIP formatında indirip açar. zip eklentisi olmadan ya Composer hata verir ya da çok daha yavaş çalışır.

Gerçek Dünya Senaryosu 2: Türkçe Karakter Sorunları ve mbstring

E-ticaret projelerinde en sık karşılaşılan sorunlardan biri Türkçe karakterlerin yanlış işlenmesidir. mbstring olmadan şöyle bir senaryo yaşanabilir:

# mbstring olmadan bu PHP kodu yanlış sonuç verir
php -r "echo strlen('Güneş');"
# Beklenen: 5
# Alınan: 7 (çünkü ü ve ş 2 byte yer kaplıyor)

# mbstring ile doğru kullanım
php -r "echo mb_strlen('Güneş');"
# Sonuç: 5 (doğru)

# Encoding dönüşümü
php -r "echo mb_convert_encoding('Güneş', 'UTF-8', 'ISO-8859-9');"

Özellikle PDF oluşturma, e-posta gönderme ve veritabanı işlemlerinde Türkçe karakterler için mbstring hayat kurtarıcıdır. mbstring kurulumu sonrası php.ini içinde şu ayarları da yapmanızı öneririm:

# php.ini içindeki mbstring ayarları
sudo nano /etc/php/8.2/fpm/php.ini

# Şu satırları bulun ve düzenleyin:
# mbstring.language = Turkish
# mbstring.internal_encoding = UTF-8
# mbstring.http_input = UTF-8
# mbstring.http_output = UTF-8
# mbstring.encoding_translation = Off
# mbstring.detect_order = auto
# mbstring.substitute_character = none

Gerçek Dünya Senaryosu 3: API Entegrasyonu ve curl

Ödeme sistemi entegrasyonu yapan bir geliştiricinin yaşadığı senaryoyu ele alalım. curl olmadan herhangi bir HTTP isteği gönderemezsiniz:

# curl eklentisini test etmek için basit bir PHP scripti
php -r "
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://httpbin.org/get');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo 'HTTP Code: ' . $httpCode . PHP_EOL;
"

curl ile ilgili php.ini ayarları da önemlidir. Özellikle SSL sertifika doğrulaması için:

# php.ini içinde curl için CA sertifika yolu ayarla
grep -n "curl.cainfo" /etc/php/8.2/fpm/php.ini

# Eğer boşsa ayarla
sudo sed -i 's|;curl.cainfo =|curl.cainfo = /etc/ssl/certs/ca-certificates.crt|' /etc/php/8.2/fpm/php.ini

Eklenti Kurulumunu Otomatize Etme: Bash Scripti

Birden fazla sunucu yönetiyorsanız ya da otomatik kurulum scriptleri yazıyorsanız bu yaklaşım işinize yarar:

#!/bin/bash

# PHP eklentisi kurulum scripti
# Kullanım: sudo bash install_php_extensions.sh 8.2

PHP_VERSION=${1:-8.2}
EXTENSIONS=("mbstring" "curl" "zip")

echo "PHP ${PHP_VERSION} için eklentiler kuruluyor..."

# Ubuntu/Debian kontrolü
if command -v apt &> /dev/null; then
    for ext in "${EXTENSIONS[@]}"; do
        PACKAGE="php${PHP_VERSION}-${ext}"
        if dpkg -l | grep -q "${PACKAGE}"; then
            echo "[MEVCUT] ${PACKAGE} zaten kurulu"
        else
            echo "[KURULUYOR] ${PACKAGE}..."
            sudo apt install -y "${PACKAGE}"
        fi
    done
    sudo systemctl restart "php${PHP_VERSION}-fpm"

# CentOS/RHEL/AlmaLinux kontrolü
elif command -v dnf &> /dev/null; then
    for ext in "${EXTENSIONS[@]}"; do
        sudo dnf install -y "php-${ext}"
    done
    sudo systemctl restart php-fpm
fi

# Doğrulama
echo ""
echo "Kurulum doğrulanıyor..."
php -m | grep -E "mbstring|curl|zip" && echo "Tüm eklentiler aktif!" || echo "UYARI: Bazı eklentiler eksik olabilir"

Eklenti Versiyonları ve Uyumluluk

PHP 8.0 ile birlikte bazı eklentilerde davranış değişiklikleri oldu. Özellikle şunlara dikkat edin:

  • mbstring: PHP 8.0’dan itibaren bazı encoding fonksiyonları farklı davranış gösteriyor. mb_strtolower() Türkçe İ/ı karakterlerinde daha doğru çalışıyor.
  • curl: PHP 7.4’ten itibaren curl_version() dizi yapısı değişti.
  • zip: PHP 8.0 ile birlikte ZipArchive sınıfı yeni metodlar kazandı ve bazı eski metodlar deprecated oldu.

Sürüm uyumluluğunu kontrol etmek için:

# Tüm eklentilerin sürümlerini gör
php -i | grep -A2 -E "mbstring|curl|zip" | grep -E "version|Version"

# Belirli bir eklentinin detaylı bilgisi
php -i | grep -A 20 "mbstring support"

Sorun Giderme: Yaygın Hatalar ve Çözümleri

Eklenti kurulu ama hala hata alıyorum:

PHP-FPM ve CLI farklı php.ini dosyaları kullanır. CLI’da çalışan bir eklenti FPM’de çalışmayabilir.

# CLI php.ini yolunu bul
php --ini | grep "Loaded Configuration"

# FPM php.ini yolunu bul
php-fpm8.2 --ini | grep "Loaded Configuration"

# İkisini karşılaştır
diff /etc/php/8.2/cli/php.ini /etc/php/8.2/fpm/php.ini | grep extension

Shared object bulunamıyor hatası:

# Eklenti .so dosyasının varlığını kontrol et
find /usr/lib/php -name "*.so" | grep -E "mbstring|curl|zip"

# Eksikse paketi yeniden kur
sudo apt install --reinstall php8.2-curl

SELinux’tan kaynaklanan curl sorunları (CentOS/RHEL):

# SELinux'un curl'ü engelleyip engellemediğini kontrol et
sudo ausearch -c 'php-fpm' --raw | audit2allow

# Gerekirse izin ver
sudo setsebool -P httpd_can_network_connect 1

Sonuç

mbstring, curl ve zip eklentileri PHP ekosisteminin temel taşlarıdır. Bu üç eklenti olmadan modern bir PHP uygulaması çalıştırmak neredeyse imkansızdır. Kurulum süreci her ne kadar dağıtıma göre farklılık gösterse de mantık aynıdır: paketi kur, gerekirse php.ini içinde etkinleştir, servisi yeniden başlat ve doğrula.

Yeni bir sunucu kurulumunda ya da mevcut bir sunucuya yeni bir PHP sürümü eklerken bu eklentileri standart checklist’inizin bir parçası haline getirmenizi öneririm. Yukarıda paylaştığım bash scriptini kendi ortamınıza uyarlayarak kurulum süreçlerini otomatize edebilirsiniz. Docker kullanıyorsanız Dockerfile’ınıza bu eklentileri eklemeyi asla atlamayın.

Özellikle Türkçe dil desteği gerektiren projeler için mbstring’in sadece kurulması yetmez; php.ini içindeki encoding ayarlarını da düzgünce yapılandırmalısınız. Aksi takdirde geliştirme ortamında çalışan bir uygulama production’da karakter sorunlarıyla karşılaşabilir. Küçük bir konfigürasyon farkı, büyük problemlere yol açabilir.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir