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

Sağlayıcı	Gönderi Oluştur	İptal	Takip	Ücretlendirme	Webhook
Yurtiçi Kargo	✅	✅	✅	⏳	✅
Aras Kargo	✅	✅	✅	⏳	✅
MNG Kargo	✅	✅	✅	⏳	✅
PTT Kargo	✅	✅	✅	⏳	✅
Sürat Kargo	✅	✅	✅	⏳	✅
HepsiJet	✅	✅	✅	⏳	✅
Trendyol Express	✅	✅	✅	⏳	✅
Sendeo	✅	✅	✅	⏳	✅
Kolay Gelsin	✅	✅	✅	⏳	✅
UPS	✅	✅	✅	⏳	✅
DHL	✅	✅	✅	⏳	✅
FedEx	✅	✅	✅	⏳	✅

✅ 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ı

Kalıp	Kullanım Yeri	Neden?
Template Method	`AbstractCarrier`	Gönderi akışı sabit, sağlayıcıya özel adımlar değişken
Strategy	HashGenerator, Serializer, ResponseParser	Her sağlayıcı farklı API formatı
Factory + Registry	`CarrierFactory`	Ayarlardan sağlayıcı oluşturma, OCP uyumlu
Builder	`ShipmentRequestBuilder`	Fluent, immutable (her method clone döner)
Adapter	`ResponseParser`'lar	Farklı API yanıtlarını birleşik DTO'ya dönüştürme
Decorator	`LoggingCarrier`, `RetryCarrier`	Şeffaf cross-cutting concern'ler
Observer	PSR-14 Events	Gönderi yaşam döngüsü olayları
State	`ShipmentStateMachine`	Geçerli durum geçişleri
Chain of Responsibility	`ValidationPipeline`	Tüm hataları topla, kısa devre yapma
Value Object	`Address`, `Package`, `Money`	Immutable, self-validating
Null Object	`NullShipmentRepository`	Koşulsuz çalışma

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

lbali / truecargo

Maintainers

Package info

Statistics

Security