README

Beta sürüm (v0.1.0-beta) — Üretim ortamında kullanmadan önce test dikkatlice yapılmalıdır. API yüzeyi kararlı sürümünden önce kırılabilir.

Tüm Türk kargo sağlayıcılarını tek bir birleşik API altında toplayan, framework-bağımsız PHP paketi. Laravel entegrasyonu dahil.

Bir sağlayıcıdan diğerine geçmek için yapmanız gereken tek şey ayarları değiştirmek — kod aynı kalır.

Özellikler

• 12 Sağlayıcı: Yurtiçi Kargo, Aras Kargo, MNG Kargo, PTT Kargo, Sürat Kargo, HepsiJet, Trendyol Express, Sendeo, Kolay Gelsin, UPS, DHL, FedEx
• Birleşik API: Tek sözleşme (CarrierInterface) altında tüm sağlayıcılar
• Framework-bağımsız çekirdek: PSR-18 HTTP, PSR-14 event, PSR-16 cache, PSR-3 log
• Laravel köprüsü: ServiceProvider, Facade, config, migration, Eloquent depo
• OOP Tasarım Kalıpları: Template Method, Strategy, Factory+Registry, Builder, Adapter, Decorator, Observer, State, Chain of Responsibility, Value Object, Null Object
• PHPStan seviye 8 — sıfır hata hedefi
• Güvenli: Fail-closed webhook doğrulama, hassas veri maskeleme, retry güvenliği

Özellik Matrisi

✅ hazır · ⏳ yol haritasında · ❌ desteklenmiyor

Gereksinimler

• PHP 8.2+
• ext-simplexml, ext-dom
• PSR-18 uyumlu bir HTTP istemcisi (guzzlehttp/guzzle tavsiye edilir)
• Laravel 10+ (Laravel kullanımı için — opsiyonel)

Kurulum

composer require lbali/truecargo guzzlehttp/guzzle

Laravel için ayar ve migration dosyalarını yayınlayın:

php artisan vendor:publish --tag=truecargo-config
php artisan vendor:publish --tag=truecargo-migrations
php artisan migrate

Ardından .env dosyanızı doldurun:

TRUECARGO_DEFAULT=yurtici

TRUECARGO_YURTICI_USERNAME=kullanici_adi
TRUECARGO_YURTICI_PASSWORD=sifre

TRUECARGO_ARAS_USERNAME=kullanici_adi
TRUECARGO_ARAS_PASSWORD=sifre
TRUECARGO_ARAS_CUSTOMER_CODE=musteri_kodu

Hızlı Başlangıç — Laravel

use TrueCargo\Builder\ShipmentRequestBuilder;
use TrueCargo\Enums\PaymentType;
use TrueCargo\Enums\ServiceType;
use TrueCargo\Facades\TrueCargo;
use TrueCargo\ValueObjects\Address;
use TrueCargo\ValueObjects\Package;
use TrueCargo\ValueObjects\Recipient;
use TrueCargo\ValueObjects\Sender;

$senderAddress = new Address(
    line1: 'Maslak Mah. Büyükdere Cad. No:255',
    city: 'İstanbul',
    district: 'Sarıyer',
    postalCode: '34485',
);

$recipientAddress = new Address(
    line1: 'Kızılay Mah. Atatürk Bulvarı No:12 D:4',
    city: 'Ankara',
    district: 'Çankaya',
    postalCode: '06420',
);

$shipment = ShipmentRequestBuilder::create()
    ->sender(new Sender(name: 'Levent Bali', phone: '5551234567', address: $senderAddress))
    ->recipient(new Recipient(name: 'Ahmet Yılmaz', phone: '5559876543', address: $recipientAddress))
    ->package(new Package(weight: 2.5, width: 30, height: 20, depth: 15))
    ->serviceType(ServiceType::Express)
    ->paymentType(PaymentType::SenderPays)
    ->build();

// Yurtiçi Kargo ile gönder
$response = TrueCargo::carrier('yurtici')->createShipment($shipment);

// Aynı kod, farklı sağlayıcı — sadece isim değişir
$response = TrueCargo::carrier('aras')->createShipment($shipment);
$response = TrueCargo::carrier('mng')->createShipment($shipment);

if ($response->isSuccessful()) {
    echo "Takip numarası: {$response->trackingNumber}";
}

Takip

$tracking = TrueCargo::carrier('yurtici')->track('1234567890');

foreach ($tracking->events as $event) {
    echo $event->occurredAt->format('Y-m-d H:i').' — '.$event->description.PHP_EOL;
}

if ($tracking->isDelivered()) {
    echo 'Teslim edildi: '.$tracking->recipientName;
}

İptal

use TrueCargo\DataTransferObjects\CancelRequest;

$response = TrueCargo::carrier('yurtici')->cancelShipment(new CancelRequest(
    trackingNumber: '1234567890',
    reason: 'Müşteri isteği',
));

Framework-bağımsız Kullanım

Laravel olmadan da çalışır:

use GuzzleHttp\Client;
use TrueCargo\Factory\CarrierFactory;
use TrueCargo\TrueCargoManager;

$config = [
    'default' => 'yurtici',
    'carriers' => [
        'yurtici' => [
            'driver' => 'yurtici',
            'endpoint' => 'https://webservices.yurticikargo.com/...',
            'username' => 'kullanici',
            'password' => 'sifre',
        ],
    ],
];

$manager = new TrueCargoManager(
    config: $config,
    factory: new CarrierFactory,
    httpClient: new Client,
);

$response = $manager->carrier('yurtici')->createShipment($shipment);

OOP Tasarım Kalıpları

Webhook Entegrasyonu

routes/truecargo.php altında otomatik kayıtlı rota:

POST /truecargo/webhook/{carrier}

Güvenlik (gerçek uygulama):

• Her sağlayıcı kendi imza/hash doğrulamasını yapar. HMAC imzası ham istek gövdesi üzerinden hesaplanır — array yeniden serileştirilmez (whitespace/sıralama bozulmaz).
• İmza geçersizse 401 döner — sessiz kabul yoktur.
• Event'e dispatch edilen WebhookPayload::rawPayload alanı SensitiveDataRedactor'dan geçirilmiş şekilde taşınır.
• EloquentShipmentRepository raw_response kolonunu varsayılan olarak maskelenmiş yazar; truecargo.store_raw_response=false ile hiç yazmayı kapatabilirsiniz.
• IpAllowlistMiddleware paket içinde tanımlıdır ve webhook route'una otomatik bağlanır. truecargo.webhook.allowed_ips listesi doluysa eşleşmeyen IP'ler 403 alır; liste boşsa middleware pass-through davranır.

Event dinleme (Laravel):

use Illuminate\Support\Facades\Event;
use TrueCargo\Events\WebhookReceived;

Event::listen(WebhookReceived::class, function (WebhookReceived $event) {
    $payload = $event->payload;
    // Gönderi durumunu güncelle, kullanıcıya bildirim gönder vb.
});

Retry Güvenliği

RetryCarrier dekoratörü sadece idempotent işlemleri yeniden dener:

• ✅ track() — retry yapılır
• ✅ getRate() — retry yapılır
• ❌ createShipment() — ASLA retry yapılmaz (çift gönderi riski)
• ❌ cancelShipment() — sağlayıcıya göre değişir, riskli kabul edilir

Bilinen Kısıtlamalar

• Ücretlendirme (getRate) henüz çoğu sağlayıcıda UnsupportedOperationException fırlatıyor — yol haritasında
• Etiket PDF indirme şu an DTO üzerinden URL olarak döner; binary download yardımcı metotları eklenecek
• Çoklu paket gönderimi bazı sağlayıcılarda tek ana paket olarak gönderiliyor — kümülatif metrikler kullanılıyor
• Sağlayıcı API'leri değiştikçe ResponseParser'lar güncellenmelidir — PR'lar beklenir

Güvenlik

Güvenlik açığı bulursanız lütfen SECURITY.md dosyasını okuyun ve özel olarak bildirin.

Katkıda Bulunma

Katkı kılavuzu: CONTRIBUTING.md.

Lisans

MIT — bkz. LICENSE.

Yazar

Levent Bali — github.com/lbali