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.inidekiupload_max_filesizesınırını aşıyor.UPLOAD_ERR_FORM_SIZE(2) – HTML formundakiMAX_FILE_SIZEdeğ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
- 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.) - php.ini ayarları:
upload_max_filesize,post_max_sizevemax_file_uploadsdeğerleri ihtiyaca göre ayarlanır. - İstek kontrolü:
$_SERVER['REQUEST_METHOD']POSTmu?isset($_FILES['dosya'])var mı? - Hata kontrolü:
$_FILES['dosya']['error'] === UPLOAD_ERR_OKise işlem devam eder. - Boyut ve tip doğrulama:
sizevetypeya da dosya uzantısı kontrol edilir. - Güvenli dosya adı:
basename()vepreg_replace()ile zararlı karakterler temizlenir. - Kalıcı konuma taşıma:
move_uploaded_file()fonksiyonu kullanılaraktmp_namedeğeri/uploads/gibi bir klasöre taşınır. - 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_DIRhatası alırsanızphp.inidesys_temp_dirayarını kontrol edin. - Dosya boyutu sınırı:
upload_max_filesizevepost_max_sizedeğerleri birbirinden büyük olmalı; aksi takdirdeUPLOAD_ERR_INI_SIZEdö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 zamanbasename()ve karakter filtreleme uygulayın. - Çoklu dosya yükleme:
$_FILESdizisi ç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_OKile karşılaştırın, aksi takdirde kullanıcıya açıklayıcı mesaj verin. - Dosya boyutunu
$_FILES['dosya']['size']ile kontrol edipphp.inideki limitleri aşmadığından emin olun. - MIME tipini
finfo_file()ile doğrulayın, uzantıyı isepathinfo()ile alın. - Güvenli bir dosya adı oluşturmak için özel karakterleri
_ile değiştirin veuniqid()ekleyin. - Hedef klasörün varlığını
is_dir()ile kontrol edin, yoksamkdir()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.
Yorumlar
Henüz onaylanmış yorum yok. İlk yorumu siz yazın.
Yorum yaz
Yorumunuz yönetici onayından sonra yayınlanır.