Sayfa yükleniyor

Destek Müşteri Girişi Sepet (0)

Ders 68 – move_uploaded_file ve MIME kontrolü

PHP'de dosya yüklemelerini güvenli bir şekilde taşımak, MIME tipini finfo ile doğrulamak ve yaygın hatalardan kaçınmak için adım adım rehber.

Ders 68 – move_uploaded_file ve MIME kontrolü

Web uygulamalarında dosya yükleme işlemi, kullanıcı deneyimini artırırken aynı zamanda güvenlik risklerini de beraberinde getirir. Yanlış yapılandırılmış bir dosya yükleme süreci, sunucunuza zararlı kodların sızmasına, veri sızıntılarına ve hizmet dışı kalmalara yol açabilir. Bu derste, move_uploaded_file fonksiyonunu doğru kullanmayı, is_uploaded_file kontrolünü zorunlu kılmayı ve finfo sınıfı ile MIME tipini güvenilir bir şekilde doğrulamayı öğreneceksiniz. Ayrıca, dosya adlarını rastgeleleştirerek dizin traversi saldırılarına karşı önlem almayı da göreceksiniz.

Temel Kavramlar

Dosya yükleme sürecinde üç temel unsur vardır:

  • is_uploaded_file: Kullanıcının gönderdiği dosyanın gerçekten HTTP POST ile yüklenip yüklenmediğini kontrol eder. Bu kontrol, sahte bir dosya yolu üzerinden move_uploaded_file çalıştırılmasını engeller.
  • move_uploaded_file: Geçici klasörden (genellikle /tmp) kalıcı bir hedef klasöre güvenli bir şekilde taşıma işlemini gerçekleştirir. Bu fonksiyon yalnızca is_uploaded_file doğrulamasını geçmiş dosyalar için çalışır.
  • MIME Tipi: Dosyanın gerçek içeriğini belirten bir tanımlayıcıdır. Uzantıya bakmak yanıltıcı olabilir; .jpg uzantılı bir dosya aslında bir .php dosyası da olabilir. finfo sınıfı, dosyanın içeriğine bakarak gerçek MIME tipini döndürür.

Bu üç unsur bir araya geldiğinde, dosya yükleme süreci hem fonksiyonel hem de güvenli bir hâle gelir.

Adım Adım Uygulama

Aşağıdaki adımlar, bir dosya yükleme formu oluşturup, sunucu tarafında güvenli bir şekilde işlemek için izlenmesi gereken süreçleri gösterir.

  1. HTML Formunu Hazırlayın: enctype="multipart/form-data" ve method="POST" özelliklerini ekleyin.
  2. Geçici Dosyayı Kontrol Edin: $_FILES dizisindeki error değerini kontrol edin.
  3. is_uploaded_file ile kaynağın geçerli bir yükleme olduğunu doğrulayın.
  4. finfo ile MIME tipini alın ve izin verilen tiplerle karşılaştırın.
  5. Dosya adını rastgeleleştirin ve hedef klasöre taşıma işlemini move_uploaded_file ile gerçekleştirin.
  6. Sonuçları kullanıcıya bildirin ancak üretim ortamında detaylı hata mesajlarını gizleyin.

Bu adımların her birini kod örnekleriyle pekiştireceğiz.

Örnek Kod

Aşağıdaki iki kod bloğu, aynı işlevi iki farklı yaklaşımla (fonksiyon ve sınıf) sunar. İhtiyacınıza göre birini tercih edebilirsiniz.

<?php
// dosya_yukle_fonksiyon.php
function guvenliDosyaYukle(array $dosya, string $hedefKlasor = __DIR__.'/uploads/') {
    // 1. Hata kontrolü
    if ($dosya['error'] !== UPLOAD_ERR_OK) {
        throw new RuntimeException('Dosya yükleme hatası: '.$dosya['error']);
    }
    // 2. Geçici dosyanın gerçekten bir yükleme olup olmadığını kontrol et
    if (!is_uploaded_file($dosya['tmp_name'])) {
        throw new RuntimeException('Geçersiz dosya kaynağı.');
    }
    // 3. MIME tipini finfo ile al
    $finfo = new finfo(FILEINFO_MIME_TYPE);
    $mime  = $finfo->file($dosya['tmp_name']);
    $izinliMIMEtipleri = ['image/jpeg', 'image/png', 'application/pdf'];
    if (!in_array($mime, $izinliMIMEtipleri, true)) {
        throw new RuntimeException('İzin verilmeyen dosya tipi: '.$mime);
    }
    // 4. Rastgele dosya adı üret (örnek: 32 karakter hex + uzantı)
    $uzanti = pathinfo($dosya['name'], PATHINFO_EXTENSION);
    $yeniAd = bin2hex(random_bytes(16)).'.'.strtolower($uzanti);
    // 5. Hedef klasörün varlığını ve yazma iznini kontrol et
    if (!is_dir($hedefKlasor) && !mkdir($hedefKlasor, 0755, true)) {
        throw new RuntimeException('Hedef klasör oluşturulamadı.');
    }
    $hedefYol = $hedefKlasor.$yeniAd;
    // 6. Dosyayı taşı
    if (!move_uploaded_file($dosya['tmp_name'], $hedefYol)) {
        throw new RuntimeException('Dosya taşınamadı.');
    }
    // 7. Başarıyla yüklendi, dosya yolunu döndür
    return $hedefYol;
}

// Kullanım örneği
try {
    $yuklenenDosya = guvenliDosyaYukle($_FILES['dosya']);
    echo 'Dosya başarıyla yüklendi: '.htmlspecialchars(basename($yuklenenDosya));
} catch (RuntimeException $e) {
    // Üretim ortamında $e->getMessage() yerine genellikle genel bir mesaj gösterilir
    echo 'Hata: '.htmlspecialchars($e->getMessage());
}
?>
<?php
// DosyaYukleme.php – sınıf tabanlı yaklaşım
class DosyaYukleyici {
    private $hedefKlasor;
    private $izinliMIMEtipleri = ['image/jpeg', 'image/png', 'application/pdf'];
    private $finfo;

    public function __construct(string $hedefKlasor = __DIR__.'/uploads/') {
        $this->hedefKlasor = rtrim($hedefKlasor, '/').'/';
        $this->finfo = new finfo(FILEINFO_MIME_TYPE);
        if (!is_dir($this->hedefKlasor) && !mkdir($this->hedefKlasor, 0755, true)) {
            throw new RuntimeException('Yükleme klasörü oluşturulamadı.');
        }
    }

    public function yukle(array $dosya): string {
        $this->kontrolHata($dosya);
        $this->kontrolIsUploaded($dosya['tmp_name']);
        $mime = $this->finfo->file($dosya['tmp_name']);
        $this->kontrolMime($mime);
        $yeniAd = $this->rasgeleDosyaAdi($dosya['name']);
        $hedefYol = $this->hedefKlasor.$yeniAd;
        if (!move_uploaded_file($dosya['tmp_name'], $hedefYol)) {
            throw new RuntimeException('Dosya taşınamadı.');
        }
        return $hedefYol;
    }

    private function kontrolHata(array $dosya): void {
        if ($dosya['error'] !== UPLOAD_ERR_OK) {
            throw new RuntimeException('Yükleme hatası: '.$dosya['error']);
        }
    }

    private function kontrolIsUploaded(string $tmpName): void {
        if (!is_uploaded_file($tmpName)) {
            throw new RuntimeException('Geçersiz dosya kaynağı.');
        }
    }

    private function kontrolMime(string $mime): void {
        if (!in_array($mime, $this->izinliMIMEtipleri, true)) {
            throw new RuntimeException('İzin verilmeyen MIME tipi: '.$mime);
        }
    }

    private function rasgeleDosyaAdi(string $orijinalAd): string {
        $uzanti = pathinfo($orijinalAd, PATHINFO_EXTENSION);
        return bin2hex(random_bytes(16)).'.'.strtolower($uzanti);
    }
}

// Kullanım
try {
    $yukleyici = new DosyaYukleyici();
    $yol = $yukleyici->yukle($_FILES['dosya']);
    echo 'Dosya yüklendi: '.htmlspecialchars(basename($yol));
} catch (RuntimeException $e) {
    echo 'Hata: '.htmlspecialchars($e->getMessage());
}
?>

Sık Karşılaşılan Hatalar ve Çözümleri

  • PHP'nin dosya yükleme limitini aşmak: upload_max_filesize ve post_max_size ayarlarını php.ini'de yükseltin.
  • Geçici klasöre yazma izni yok: /tmp (veya sys_temp_dir) klasörünün PHP sürecine yazma izni olduğundan emin olun.
  • MIME tipinin application/octet-stream olarak gelmesi: Bazı tarayıcılar dosyayı tanımlayamıyorsa, ek bir uzantı kontrolü (ör. getimagesize ile resim doğrulama) ekleyin.
  • Dosya adı çakışması: Rastgele isim üretmek (ör. bin2hex(random_bytes(16))) çakışma riskini ortadan kaldırır.
  • Dosya yolu Traversal (../) saldırısı: basename() ve rastgele isimlendirme, kullanıcı tarafından gönderilen yolu tamamen görmezden gelerek bu saldırıyı engeller.

Kontrol Listesi

  • Form enctype="multipart/form-data" ve method="POST" kullanıyor mu?
  • $_FILES['dosya']['error'] == UPLOAD_ERR_OK kontrolü yapıldı mı?
  • is_uploaded_file() ile geçici dosyanın gerçek bir yükleme olup olmadığı doğrulandı mı?
  • MIME tipini finfo ile aldınız ve sadece izin verilen tipleri kabul ettiniz mi?
  • Dosya adı rastgeleleştirildi ve hedef klasöre güvenli bir yol (ör. realpath) ile taşındı mı?
  • Hedef klasör var ve 0755 (veya daha kısıtlı) izinlerine sahip mi?
  • Üretim ortamında kullanıcıya teknik hata detayları gösterilmiyor mu?

SSS

1. finfo sınıfı sunucumda yüklü değil, ne yapmalıyım?

Çoğu modern Linux dağıtımı php-fileinfo paketini içerir. apt-get install php-fileinfo (Debian/Ubuntu) veya yum install php-fileinfo (CentOS) komutlarıyla paketi kurabilirsiniz. Windows ortamında ise php.ini dosyasındaki extension=fileinfo satırının başındaki noktalı virgülü kaldırın ve web sunucusunu yeniden başlatın.

2. MIME tipini sadece uzantıya göre kontrol etmek güvenli mi?

Hayır. Uzantı sadece kullanıcı dostu bir gösterim sağlar; dosyanın gerçek içeriği hakkında hiçbir garanti vermez. finfo gibi içerik‑tabanlı doğrulama yöntemleri kullanılmalıdır.

3. Büyük dosyaları parça‑parça nasıl kontrol edebilirim?

PHP 5.5+ stream_copy_to_stream ve filter fonksiyonlarıyla dosyayı okurken aynı anda MIME kontrolü yapabilirsiniz. Ancak çoğu senaryoda upload_max_filesize ve post_max_size sınırlarını ayarlamak yeterli olur.

Özet

Bu derste, move_uploaded_file ve is_uploaded_file fonksiyonlarının zorunlu ikilisi, finfo ile MIME tipinin güvenilir bir şekilde doğrulanması ve dosya adının rastgeleleştirilerek dizin traversi saldırılarına karşı korunması konularını adım adım inceledik. Güvenli bir dosya yükleme süreci, sadece fonksiyonları doğru sırada çağırmakla kalmaz, aynı zamanda sunucu yapılandırması, hata yönetimi ve kullanıcıya gösterilecek mesajların da dikkatli bir şekilde tasarlanmasını gerektirir. Bu ilkeleri uyguladığınız sürece, PHP tabanlı projelerinizde dosya yükleme güvenliğini sağlam bir temele oturtmuş olacaksınız.

Paylaş

Yorumlar

Henüz onaylanmış yorum yok. İlk yorumu siz yazın.

Yorum yaz

Yorumunuz yönetici onayından sonra yayınlanır.

İlgili yazılar

Ders 100 – İleri yol haritası

PHP serisinin son dersinde ileri seviye konular, framework seçimi, Composer ekosistemi, mikro pro…

Ders 99 – Güvenli yapılandırma kontrol listesi

Üretim ortamı için PHP yapılandırma ayarlarını adım adım kontrol eden, hatasız ve güvenli bir yap…

Ders 98 – OpCache ve performans ipuçları

OpCache'ın çalışma prensibi, yapılandırma adımları ve gerçek dünyada performans artırmak için pra…

Ders 97 – Fibers’a kısa bakış (PHP 8.1)

PHP 8.1 ile gelen Fibers özelliğini adım adım öğrenin, kooperatif concurrency kavramını kavrayın …

Demo
Büyütülmüş Görsel