PHPackages                             lbali/truecargo - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. lbali/truecargo

ActiveLibrary[API Development](/categories/api)

lbali/truecargo
===============

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

00PHPCI failing

Since Apr 17Pushed 1mo agoCompare

[ Source](https://github.com/lbali/truecargo)[ Packagist](https://packagist.org/packages/lbali/truecargo)[ RSS](/packages/lbali-truecargo/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

TrueCargo
=========

[](#truecargo)

[![CI](https://github.com/lbali/truecargo/actions/workflows/ci.yml/badge.svg)](https://github.com/lbali/truecargo/actions/workflows/ci.yml)[![Lisans: MIT](https://camo.githubusercontent.com/532d0a7409607d6ed53acfa1adf94742e46077c081087ecd9d6b6edfe65997ec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6973616e732d4d49542d626c75652e737667)](LICENSE)[![PHP 8.2+](https://camo.githubusercontent.com/5ed842996550cad148e16d3ad4738491b8319d2fbf7bba88eeeee0cb4bf9b736/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d373737626234)](composer.json)[![PHPStan](https://camo.githubusercontent.com/d6bf4886ee4c8c1b05494ebaa7281c13874116a9061a30022e70c8addfbbeac8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d3446354439352e737667)](phpstan.neon)

> **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
----------

[](#ö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
---------------

[](#özellik-matrisi)

SağlayıcıGönderi OluşturİptalTakipÜcretlendirmeWebhookYurtiç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
-------------

[](#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
-------

[](#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
-------------------------

[](#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

[](#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

[](#i̇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
---------------------------

[](#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ı
---------------------

[](#oop-tasarım-kalıpları)

KalıpKullanım YeriNeden?Template Method`AbstractCarrier`Gönderi akışı sabit, sağlayıcıya özel adımlar değişkenStrategyHashGenerator, Serializer, ResponseParserHer sağlayıcı farklı API formatıFactory + Registry`CarrierFactory`Ayarlardan sağlayıcı oluşturma, OCP uyumluBuilder`ShipmentRequestBuilder`Fluent, immutable (her method clone döner)Adapter`ResponseParser`'larFarklı API yanıtlarını birleşik DTO'ya dönüştürmeDecorator`LoggingCarrier`, `RetryCarrier`Şeffaf cross-cutting concern'lerObserverPSR-14 EventsGönderi yaşam döngüsü olaylarıState`ShipmentStateMachine`Geçerli durum geçişleriChain of Responsibility`ValidationPipeline`Tüm hataları topla, kısa devre yapmaValue Object`Address`, `Package`, `Money`Immutable, self-validatingNull Object`NullShipmentRepository`Koşulsuz çalışmaWebhook Entegrasyonu
--------------------

[](#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
---------------

[](#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
--------------------

[](#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)

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

Katkıda Bulunma
---------------

[](#katkıda-bulunma)

Katkı kılavuzu: [CONTRIBUTING.md](CONTRIBUTING.md).

Lisans
------

[](#lisans)

MIT — bkz. [LICENSE](LICENSE).

Yazar
-----

[](#yazar)

**Levent Bali** — [github.com/lbali](https://github.com/lbali)

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance59

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/de16c862cc0348f2811b0ddf98ae951a02809b69c665c374a53e43b338003c2a?d=identicon)[lbali](/maintainers/lbali)

---

Top Contributors

[![lbali](https://avatars.githubusercontent.com/u/529853?v=4)](https://github.com/lbali "lbali (3 commits)")

### Embed Badge

![Health badge](/badges/lbali-truecargo/health.svg)

```
[![Health](https://phpackages.com/badges/lbali-truecargo/health.svg)](https://phpackages.com/packages/lbali-truecargo)
```

###  Alternatives

[facebook/php-business-sdk

PHP SDK for Facebook Business

90923.5M35](/packages/facebook-php-business-sdk)[hubspot/api-client

Hubspot API client

24015.5M18](/packages/hubspot-api-client)[botman/driver-telegram

Telegram driver for BotMan

93452.6k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)