Sayfa yükleniyor

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

Ders 67 – Dosya yükleme temelleri

PHP ile dosya yüklemenin temelleri, $_FILES yapısı, hata kodları ve güvenli bir şekilde dosya taşıma adımları detaylı olarak anlatılıyor.

Ders 67 – Dosya yükleme temelleri

Web uygulamalarında kullanıcıların resim, belge ya da video gibi dosyaları sunucuya göndermesi oldukça yaygın bir senaryodur. Doğru bir dosya yükleme süreci, hem kullanıcı deneyimini artırır hem de güvenlik açıklarını en aza indirir. Bu derste, PHP'nin yerleşik $_FILES süperglobali, hata kodları, geçici dosya konumu (tmp_name) ve dosyanın kalıcı bir konuma taşınması adım adım incelenecek.

Temeller

$_FILES dizisi, bir HTTP POST isteğiyle gönderilen her dosya için bir alt dizi oluşturur. Alt dizinin en çok kullanılan anahtarları şunlardır:

  • name – Kullanıcının seçtiği dosyanın orijinal adı.
  • type – MIME tipi (ör. image/jpeg).
  • tmp_name – PHP tarafından oluşturulan geçici dosya yolu.
  • error – Yükleme sırasında oluşan hata kodu.
  • size – Dosyanın bayt cinsinden boyutu.

Hata kodları UPLOAD_ERR_* sabitleriyle temsil edilir. En yaygın olanları:

  • UPLOAD_ERR_OK (0) – Sorunsuz yükleme.
  • UPLOAD_ERR_INI_SIZE (1) – php.inideki upload_max_filesize sınırını aşıyor.
  • UPLOAD_ERR_FORM_SIZE (2) – HTML formundaki MAX_FILE_SIZE değerini aşıyor.
  • UPLOAD_ERR_PARTIAL (3) – Dosya sadece kısmen yüklendi.
  • UPLOAD_ERR_NO_FILE (4) – Hiç dosya seçilmedi.
  • UPLOAD_ERR_NO_TMP_DIR (6) – Geçici klasör eksik.
  • UPLOAD_ERR_CANT_WRITE (7) – Disk üzerine yazılamıyor.
  • UPLOAD_ERR_EXTENSION (8) – PHP uzantısı yüklemeyi durdurdu.

Adım adım dosya yükleme süreci

  1. HTML tarafı: Kullanıcıdan dosya alacak bir <input type="file"> elemanı oluşturulur. (Bu makalede form kodu göstermeyeceğiz, sadece PHP kısmına odaklanacağız.)
  2. php.ini ayarları: upload_max_filesize, post_max_size ve max_file_uploads değerleri ihtiyaca göre ayarlanır.
  3. İstek kontrolü: $_SERVER['REQUEST_METHOD'] POST mu? isset($_FILES['dosya']) var mı?
  4. Hata kontrolü: $_FILES['dosya']['error'] === UPLOAD_ERR_OK ise işlem devam eder.
  5. Boyut ve tip doğrulama: size ve type ya da dosya uzantısı kontrol edilir.
  6. Güvenli dosya adı: basename() ve preg_replace() ile zararlı karakterler temizlenir.
  7. Kalıcı konuma taşıma: move_uploaded_file() fonksiyonu kullanılarak tmp_name değeri /uploads/ gibi bir klasöre taşınır.
  8. Sonuç bildirimi: Kullanıcıya başarılı/başarısız mesajı gösterilir.

Örnek kod

Aşağıdaki örnek, temel bir dosya yükleme işlemini tek bir dosyada (ör. ders67.php) nasıl yapabileceğinizi gösterir.

<?php
// ders67.php - Basit dosya yükleme örneği
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['dosya'])) {
    $file = $_FILES['dosya'];
    // 1. Hata kontrolü
    if ($file['error'] !== UPLOAD_ERR_OK) {
        echo 'Yükleme hatası: ' . $file['error'];
        exit;
    }
    // 2. Boyut kontrolü (5 MB sınırı)
    $maxSize = 5 * 1024 * 1024; // 5 MB
    if ($file['size'] > $maxSize) {
        echo 'Dosya çok büyük. Maksimum 5 MB olmalı.';
        exit;
    }
    // 3. MIME tipi ve uzantı kontrolü
    $allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
    $allowedExt   = ['jpg', 'jpeg', 'png', 'pdf'];
    $finfo = new finfo(FILEINFO_MIME_TYPE);
    $mime  = $finfo->file($file['tmp_name']);
    $ext   = strtolower(pathinfo($file['name'], PATHINFO_EXTENSION));
    if (!in_array($mime, $allowedTypes) || !in_array($ext, $allowedExt)) {
        echo 'İzin verilen dosya tipleri: JPEG, PNG, PDF.';
        exit;
    }
    // 4. Güvenli dosya adı oluşturma
    $baseName = preg_replace('/[^a-zA-Z0-9_-]/', '_', pathinfo($file['name'], PATHINFO_FILENAME));
    $newName  = $baseName . '_' . uniqid() . '.' . $ext;
    // 5. Hedef klasör ve taşıma
    $uploadDir = __DIR__ . '/uploads/';
    if (!is_dir($uploadDir)) {
        mkdir($uploadDir, 0755, true);
    }
    $destPath = $uploadDir . $newName;
    if (move_uploaded_file($file['tmp_name'], $destPath)) {
        echo 'Dosya başarıyla yüklendi: ' . htmlspecialchars($newName);
    } else {
        echo 'Dosya taşıma sırasında bir hata oluştu.';
    }
} else {
    echo 'Lütfen bir dosya seçip gönderin.';
}
?>

Yukarıdaki kod, dosyanın geçici konumundan kalıcı bir klasöre güvenli bir şekilde taşınmasını ve temel doğrulamaları içerir.

İkinci örnek, aynı mantığı bir sınıf içinde kapsüller ve tekrar kullanılabilir bir metod sunar.

<?php
class DosyaYukleyici {
    private $uploadDir;
    private $maxSize;
    private $allowedTypes;
    private $allowedExt;

    public function __construct($dir = 'uploads/', $maxSize = 5242880) { // 5 MB varsayılan
        $this->uploadDir = rtrim($dir, '/') . '/';
        $this->maxSize   = $maxSize;
        $this->allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
        $this->allowedExt   = ['jpg', 'jpeg', 'png', 'pdf'];
        if (!is_dir($this->uploadDir)) {
            mkdir($this->uploadDir, 0755, true);
        }
    }

    public function yukle($fileKey) {
        if (!isset($_FILES[$fileKey])) {
            throw new RuntimeException('Dosya gönderilmedi.');
        }
        $file = $_FILES[$fileKey];
        if ($file['error'] !== UPLOAD_ERR_OK) {
            throw new RuntimeException('Yükleme hatası kodu: ' . $file['error']);
        }
        if ($file['size'] > $this->maxSize) {
            throw new RuntimeException('Dosya boyutu limitini aşıyor.');
        }
        $finfo = new finfo(FILEINFO_MIME_TYPE);
        $mime  = $finfo->file($file['tmp_name']);
        $ext   = strtolower(pathinfo($file['name'], PATHINFO_EXTENSION));
        if (!in_array($mime, $this->allowedTypes) || !in_array($ext, $this->allowedExt)) {
            throw new RuntimeException('Desteklenmeyen dosya tipi.');
        }
        $baseName = preg_replace('/[^a-zA-Z0-9_-]/', '_', pathinfo($file['name'], PATHINFO_FILENAME));
        $newName  = $baseName . '_' . uniqid() . '.' . $ext;
        $destPath = $this->uploadDir . $newName;
        if (!move_uploaded_file($file['tmp_name'], $destPath)) {
            throw new RuntimeException('Dosya taşıma başarısız.');
        }
        return $newName; // Başarıyla yüklendi
    }
}

// Kullanım örneği
try {
    $yukleyici = new DosyaYukleyici();
    $kaydedilen = $yukleyici->yukle('dosya');
    echo 'Dosya yüklendi: ' . htmlspecialchars($kaydedilen);
} catch (RuntimeException $e) {
    echo 'Hata: ' . $e->getMessage();
}
?>

Sık karşılaşılan hatalar

  • Geçici klasör eksikliği: UPLOAD_ERR_NO_TMP_DIR hatası alırsanız php.inide sys_temp_dir ayarını kontrol edin.
  • Dosya boyutu sınırı: upload_max_filesize ve post_max_size değerleri birbirinden büyük olmalı; aksi takdirde UPLOAD_ERR_INI_SIZE döner.
  • İzin sorunları: Hedef klasörün PHP çalıştıran kullanıcı (genellikle www-data) tarafından yazılabilir olması gerekir.
  • Güvenlik açıkları: Doğrudan $_FILES['name'] değerini kullanmak, dosya yolu traversi (../) gibi saldırılara yol açabilir. Her zaman basename() ve karakter filtreleme uygulayın.
  • Çoklu dosya yükleme: $_FILES dizisi çoklu dosyalar için bir dizi içinde dizi olarak gelir; döngüyle işlemek gerekir.

Özet

Dosya yükleme işlemi, $_FILES yapısını doğru okumak, hata kodlarını kontrol etmek ve güvenli bir move_uploaded_file() işlemiyle kalıcı bir konuma taşımak üzerine kuruludur. Sunucu tarafı ayarları (php.ini) ve kullanıcı tarafı doğrulamaları (boyut, tip, uzantı) bir arada ele alındığında, hem performans hem de güvenlik açısından sağlam bir çözüm elde edilir.

SSS

1. $_FILES içinde birden fazla dosya gönderildiğinde nasıl erişilir?
Form elemanının adı dosya[] şeklinde tanımlanır ve PHP $_FILES['dosya']['name'][0], $_FILES['dosya']['tmp_name'][1] gibi çok boyutlu diziler oluşturur. Bir foreach döngüsüyle her bir dosya ayrı ayrı işlenir.

2. Yüklenen bir dosyanın MIME tipini güvenilir bir şekilde nasıl doğrularım?
Tarayıcı tarafından gönderilen type alanı güvenilir değildir. finfo_file() (FileInfo uzantısı) ile sunucu tarafında gerçek MIME tipi okunmalıdır.

3. Kullanıcıya hatalı bir dosya yükleme durumunda ne tür mesajlar gösterilmeli?
Geliştiriciye yönelik teknik hata kodları (ör. UPLOAD_ERR_INI_SIZE) yerine, kullanıcı dostu mesajlar ("Dosya çok büyük", "Desteklenmeyen dosya tipi") kullanılmalı ve sistem hataları log dosyasına kaydedilmelidir.

  • Formdan gelen dosyanın varlığını isset($_FILES['dosya']) ile kontrol edin.
  • Hata kodunu UPLOAD_ERR_OK ile karşılaştırın, aksi takdirde kullanıcıya açıklayıcı mesaj verin.
  • Dosya boyutunu $_FILES['dosya']['size'] ile kontrol edip php.inideki limitleri aşmadığından emin olun.
  • MIME tipini finfo_file() ile doğrulayın, uzantıyı ise pathinfo() ile alın.
  • Güvenli bir dosya adı oluşturmak için özel karakterleri _ ile değiştirin ve uniqid() ekleyin.
  • Hedef klasörün varlığını is_dir() ile kontrol edin, yoksa mkdir() ile oluşturun.
  • Dosyayı taşımak için move_uploaded_file() kullanın; başarısız olursa loglayın.
  • Üretim ortamında hata mesajlarını kullanıcıya doğrudan göstermeyin, sadece genel bir uyarı gösterin ve detayları sunucu logunda tutun.
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