# football-data.org PHP + PostgreSQL Importer

Top 5 Avrupa ligi (Premier League, La Liga, Bundesliga, Serie A, Ligue 1) için
ülke, lig, takım ve sezon bazlı maç sonuçlarını (ilk yarı + maç sonucu)
[football-data.org](https://www.football-data.org) API'sinden çekip
PostgreSQL'e kaydeder. Her kayıt, verinin geldiği API endpoint URL'siyle
(`source_url`) birlikte tutulur.

Bu proje, aynı mimarideki Transfermarkt scraper'ının API tabanlı sürümüdür:
HTML scraping yerine resmi bir REST API kullanır.

## Gereksinimler

- PHP 8.1+ (`curl`, `pdo_pgsql` eklentileri açık olmalı)
- PostgreSQL 13+
- Ücretsiz bir football-data.org API token'ı: https://www.football-data.org/client/register

## Klasör yapısı

```
config/config.php        -> DB bağlantısı + API ayarları + lig kodları
sql/schema.sql            -> PostgreSQL tabloları
src/Database.php          -> Sadece DB (PDO) işlemleri
src/FootballDataClient.php-> Sadece API isteği + JSON parse işlemleri
scripts/run.php            -> Son 5 sezonu uçtan uca işleyen başlangıç scripti
autoload.php               -> Basit PSR-4 autoloader
```

## Kurulum

1. PostgreSQL'de veritabanını oluşturun:
   ```bash
   createdb football_data
   ```

2. Token ve bağlantı bilgilerini ortam değişkenleriyle ayarlayın:
   ```bash
   export FOOTBALL_DATA_API_TOKEN=xxxxxxxxxxxxxxxx
   export DB_HOST=127.0.0.1
   export DB_PORT=5432
   export DB_NAME=football_data
   export DB_USER=postgres
   export DB_PASSWORD=postgres
   ```

3. Şemayı oluşturun ve importu başlatın:
   ```bash
   php scripts/run.php --init-schema
   ```

   Sonraki çalıştırmalarda `--init-schema` gerekmez (idempotent'tir).

## Kullanım seçenekleri

```bash
# Varsayılan: son 5 tam sezon, 5 lig
php scripts/run.php

# Belirli sezonlar (season = sezonun başladığı yıl, örn. 2024 = 2024/2025)
php scripts/run.php --seasons=2020,2021,2022,2023,2024

# Sadece belirli ligler (kod: PL, PD, BL1, SA, FL1)
php scripts/run.php --leagues=PL,SA
```

## ⚠️ Ücretsiz plan sınırlaması — önemli

football-data.org'un **ücretsiz planı sadece güncel sezona erişim verir**;
geçmiş sezonların tam listesi (son 5 yıl gibi) **ücretli / tarihsel veri
planı** gerektirir. Ücretsiz planda ayrıca:

- Dakikada 10 istek limiti vardır (script her istekten sonra varsayılan
  6 saniye bekler — `config.php` → `api.request_delay_seconds`).
- Yalnızca 12 lig ücretsiz plana dahildir (top 5 lig bunların içinde).
- Skorlar/fikstürler gecikmeli olabilir.

Script, erişiminiz olmayan bir sezon/lig kombinasyonunda API'den 403
alırsa o kombinasyonu **atlayıp devam eder** ve hatayı loglar — script
çökmez. Son 5 yılın tam verisini çekmek istiyorsanız football-data.org'un
ücretli planlarından birine ihtiyacınız olacaktır; güncel fiyat/limitleri
https://www.football-data.org/pricing adresinden kontrol edin.

## Diğer notlar

- Takım eşleştirmesi artık isim bazlı değil, football-data.org'un kendi
  `id` alanlarına göre yapılıyor (Transfermarkt sürümündeki isim eşleme
  riski burada yok).
- Sadece `status = FINISHED` olan maçlar skorla birlikte kaydedilir.
- Tüm insert/update işlemleri `fd_match_id` / `fd_team_id` /
  `fd_competition_id` üzerinden `UPSERT` (`ON CONFLICT`) ile yapılır;
  script'i tekrar tekrar çalıştırmak güvenlidir.