# Hata Çözüm Kütüphanesi

TYPO3 v13 geliştirmesinde sık karşılaşılan hatalar ve çözümleri.

---

## Kurulum Hataları

### "Could not find a version matching your minimum-stability"

**Neden:** Local package'ın sürüm bilgisi eksik.

**Çözüm:**

```json
// Paketin composer.json dosyasına version ekle
{
    "version": "1.0.0"
}

// veya root composer.json'da
{
    "minimum-stability": "dev",
    "prefer-stable": true
}
```

### "PHP extension intl is not loaded"

```bash
# DDEV'de php.ini düzenle
# .ddev/php/php.ini
extension=intl

# veya .ddev/config.yaml
webimage_extra_packages:
  - php8.2-intl

ddev restart
```

### "TYPO3 Composer Mode is required"

```bash
# Composer mode aktif etme
# public/index.php'nin varlığını doğrulayın
# vendor/autoload.php'nin varlığını doğrulayın
ddev composer install
```

---

## Cache Hataları

### "Class not found" veya "Undefined class"

```bash
# Cache ve autoload temizle
ddev exec vendor/bin/typo3 cache:flush
ddev composer dump-autoload -o
```

### Değişiklikler Görünmüyor

```bash
# Tam temizlik
ddev exec vendor/bin/typo3 cache:flush
rm -rf var/cache/*
ddev restart
```

### "Error while trying to create cache backend"

```bash
# Cache dizin izinlerini düzelt
ddev exec chmod -R 775 var/cache/
ddev exec vendor/bin/typo3 cache:flush
```

---

## Template Hataları

### "Template could not be loaded"

**Kontrol listesi:**

1. TypoScript'te templateRootPaths doğru mu?
2. Dosya adı büyük/küçük harf duyarlı (Linux'ta)
3. Extension yolu doğru mu? (`EXT:my_site_package/...`)

```typoscript
# Doğru yol tanımı
page.10 = FLUIDTEMPLATE
page.10.templateRootPaths.10 = EXT:my_site_package/Resources/Private/Templates/Page/
```

### "Partial not found"

```typoscript
# Partial yolunu kontrol et
page.10.partialRootPaths.10 = EXT:my_site_package/Resources/Private/Partials/
```

### Fluid Parsing Hatası

```html
<!-- Sorunlu: namespace eksik -->
<f:if condition="{variable}">...</f:if>

<!-- Çözüm: namespace ekle -->
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      data-namespace-typo3-fluid="true">
```

---

## Veritabanı Hataları

### "Table does not exist"

```bash
# Veritabanı şemasını güncelle
ddev exec vendor/bin/typo3 extension:setup

# veya Backend > Maintenance > Analyze Database Structure
```

### "Access denied for user"

```php
// config/system/settings.php kontrol et
'DB' => [
    'Connections' => [
        'Default' => [
            'host' => 'db',      // DDEV için
            'port' => 3306,
            'dbname' => 'db',
            'user' => 'db',
            'password' => 'db',
            'driver' => 'mysqli',
        ],
    ],
],
```

### "Duplicate entry"

```sql
-- Çakışan kayıtları kontrol et
SELECT uid, COUNT(*) FROM table_name GROUP BY uid HAVING COUNT(*) > 1;

-- Veritabanı tutarlılığını kontrol et
-- Backend > Maintenance > Analyze Database Structure
```

---

## Routing / URL Hataları

### 404 Hatası (Sayfa Var Ama Görünmüyor)

1. Site configuration doğru mu? (`config/sites/main/config.yaml`)
2. `rootPageId` doğru sayfa ID'sine işaret ediyor mu?
3. Sayfa gizli (hidden) veya silinmiş (deleted) değil mi?
4. Sayfa türü (doktype) doğru mu?

### "The requested URL was not found"

```bash
# Cache temizle
ddev exec vendor/bin/typo3 cache:flush

# Slug'ları yeniden oluştur
# Backend > Web > List > İlgili sayfanın slug alanını kontrol et
```

### Route Enhancer Çalışmıyor

```yaml
# config.yaml'da sözdizimi kontrolü
routeEnhancers:
  News:
    type: Extbase
    extension: News      # Extension adı doğru mu?
    plugin: Pi1          # Plugin adı doğru mu?
```

---

## Extension Hataları

### "Extension key is not loaded"

```bash
# Extension'ı aktif et
ddev composer require vendor/extension-name
ddev exec vendor/bin/typo3 extension:setup
ddev exec vendor/bin/typo3 cache:flush
```

### "Class does not exist" (Extension class)

```bash
# Composer autoload yenile
ddev composer dump-autoload

# Namespace kontrolü - composer.json
{
    "autoload": {
        "psr-4": {
            "Vendor\\ExtensionName\\": "Classes/"
        }
    }
}
```

---

## Frontend Hataları

### Beyaz Sayfa (White Screen)

```php
// Hata görüntülemeyi aç
// config/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['displayErrors'] = 1;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['devIPmask'] = '*';
```

### CSS/JS Yüklenmiyor

```typoscript
# TypoScript'te dosya yollarını kontrol et
page.includeCSS.styles = EXT:my_site_package/Resources/Public/Css/styles.css
# Dosyanın fiziksel olarak var olduğunu doğrulayın
```

---

## Backend Hataları

### "You are not authorized to access this page"

```bash
# Backend kullanıcı kilidini kaldır
ddev exec vendor/bin/typo3 backend:unlock

# Admin şifresini sıfırla
ddev exec vendor/bin/typo3 backend:resetpassword admin NewPassword!
```

### Install Tool Erişimi

```bash
# Install Tool'u aktif et
touch public/typo3conf/ENABLE_INSTALL_TOOL
# 1 saat sonra otomatik silinir
```

---

## DDEV Ortamı

### ddev-router "health check timed out"

**Belirti:** `ddev start` veya `ddev restart` sonrası proje başlamıyor, "ddev-router failed to become ready" hatası.

**Çözüm:** `ddev poweroff` → `docker rm -f ddev-router` → `ddev start`. Detay: [DDEV: Sorun Giderme](ddev-router-timeout-fix.md).

### "additional.php already exists and is managed by the user"

**Belirti:** DDEV başlarken bu mesaj çıkıyor. **Hata değildir.** DDEV, TYPO3 `config/system/additional.php` dosyasını üzerine yazmıyor. Yok sayabilirsiniz.

### "Port 8025 is busy, using 33000 instead"

**Belirti:** Mailpit portu 8025 başka süreçte kullanılıyor, DDEV 33000’e geçiyor.

**Çözüm (uyarıyı kaldırmak için):** `.ddev/config.yaml` içine `mailpit_http_port: "33000"` ve `mailpit_https_port: "33001"` ekleyin.

Tüm DDEV sorun giderme adımları: [DDEV: Sorun Giderme (router timeout, port, additional.php)](ddev-router-timeout-fix.md).

---

## Performans Sorunları

### Yavaş Sayfa Yükleme

1. **Cache aktif mi?** → NullBackend kullanılmadığından emin olun (production)
2. **Çok fazla extension?** → Kullanılmayanları kaldırın
3. **Büyük resimler?** → Image processing yapılandırmasını kontrol edin
4. **Veritabanı sorguları?** → Admin Panel > SQL ile kontrol edin

---

## Genel Hata Ayıklama Adımları

1. Log dosyalarını kontrol et (`var/log/`)
2. Cache temizle
3. Veritabanı şemasını güncelle
4. Composer autoload yenile
5. DDEV restart
6. PHP error log kontrol et

---

## Kaynaklar

- [TYPO3 Exception Codes](https://docs.typo3.org/m/typo3/reference-exceptions/main/en-us/)
- [TYPO3 Slack (Topluluk Desteği)](https://typo3.slack.com/)
