PHPackages                             tcgunel/omniship-common - 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. [HTTP & Networking](/categories/http)
4. /
5. tcgunel/omniship-common

ActiveLibrary[HTTP & Networking](/categories/http)

tcgunel/omniship-common
=======================

Multi-carrier shipping abstraction for PHP

v0.1.1(1w ago)050411MITPHPPHP ^8.2

Since Mar 12Pushed 1w agoCompare

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

READMEChangelogDependencies (20)Versions (4)Used By (11)

Omniship Common
===============

[](#omniship-common)

Multi-carrier shipping abstraction library for PHP. Like Omnipay, but for shipping.

Requirements
------------

[](#requirements)

- PHP 8.2+
- PSR-18 HTTP client implementation
- PSR-17 HTTP factory implementation

Installation
------------

[](#installation)

```
composer require tcgunel/omniship-common
```

Architecture
------------

[](#architecture)

```
AbstractCarrier
  ├── AbstractHttpCarrier    → REST/JSON carriers (UPS, FedEx, DHL, HepsiJet, Aras, MNG, KolayGelsin, Horoz)
  └── AbstractSoapCarrier    → SOAP/XML carriers (Yurtiçi, PTT, Sürat)

```

Each carrier is a separate package that extends the appropriate base class.

The two base classes take **different constructor arguments** — an HTTP carrier accepts a PSR-18 client, a SOAP carrier accepts a `SoapClient`. Ask before you instantiate, rather than assuming:

```
Omniship::isSoap('Yurtici');   // true
Omniship::isSoap('MNG');       // false

$carrier = Omniship::isSoap($name)
    ? Omniship::create($name)
    : Omniship::create($name, $yourPsr18Client);
```

Available Carriers
------------------

[](#available-carriers)

PackageCarrierTypeAuth`tcgunel/omniship-yurtici`Yurtiçi KargoSOAPUsername/Password`tcgunel/omniship-aras`Aras KargoHTTP/XMLUsername/Password`tcgunel/omniship-kolaygelsin`KolayGelsin (Sendeo)HTTP/JSONAPI TokenQuick Start
-----------

[](#quick-start)

```
use Omniship\Omniship;

// Create a carrier instance
$carrier = Omniship::create('Yurtici');
$carrier->initialize([
    'username' => 'your-username',
    'password' => 'your-password',
    'testMode' => true,
]);

// Create a shipment
$response = $carrier->createShipment([
    'cargoKey' => 'ORDER-001',
    'invoiceKey' => 'INV-001',
    'shipTo' => new \Omniship\Common\Address(
        name: 'Mehmet Demir',
        street1: 'Kızılay Mah. 123. Sok. No:5',
        city: 'Ankara',
        district: 'Çankaya',
        phone: '05559876543',
    ),
    'packages' => [
        new \Omniship\Common\Package(weight: 2.5, desi: 3),
    ],
])->send();

if ($response->isSuccessful()) {
    echo $response->getTrackingNumber();
    echo $response->getShipmentId();
}
```

Common Operations
-----------------

[](#common-operations)

Every carrier supports these operations:

### Create Shipment

[](#create-shipment)

```
$response = $carrier->createShipment([...])->send();
$response->isSuccessful();
$response->getTrackingNumber();
$response->getShipmentId();
$response->getBarcode();
```

### Track Shipment

[](#track-shipment)

```
$response = $carrier->getTrackingStatus([
    'trackingNumber' => '330012345678',
])->send();

$info = $response->getTrackingInfo();
$info->status;          // ShipmentStatus enum
$info->trackingNumber;
$info->events;          // TrackingEvent[]
```

### Cancel Shipment

[](#cancel-shipment)

```
$response = $carrier->cancelShipment([
    'trackingNumber' => 'ORDER-001',
])->send();

$response->isSuccessful();
$response->isCancelled();
```

Logging SOAP Traffic
--------------------

[](#logging-soap-traffic)

SOAP carriers build their own `SoapClient` from the WSDL, so there is no PSR-18 client to wrap. Supply a factory to hand them a client of your own — typically a subclass that overrides `__doRequest()` to record every exchange:

```
$carrier->setSoapClientFactory(
    fn (string $wsdl, array $options) => new LoggingSoapClient($wsdl, $options),
);
```

The factory receives the carrier's WSDL URL and SOAP options, and is called once, lazily, on the first request. Passing a ready-made client to the constructor (or `setSoapClient()`) still works when you do not need the WSDL.

Parameter Handling
------------------

[](#parameter-handling)

Parameters usually arrive from HTTP input, where everything is a string, while setters are typed for the carrier's API. `initialize()` bridges that:

- **null means "not configured"** and is skipped, so an unconfigured optional credential no longer throws a `TypeError` out of a `string`-typed setter. Setters declared `?string` still receive it, so a carrier can tell "cleared" from "never set".
- **scalars are coerced to the declared type when nothing is lost.** `'1'`reaches an `int` setter as `1`, `1` reaches a `string` setter as `'1'`. This matters because carriers disagree: Yurtiçi types `codCollectionType` as `int`, Aras as `string`, and one payload has to drive both. A lossy value (`'abc'` or `'1.5'` into an `int`) is passed through untouched so a real mistake still fails loudly.

Domain Models
-------------

[](#domain-models)

### Address

[](#address)

```
new Address(
    name: 'Alıcı Adı',
    company: 'Firma',
    street1: 'Adres satırı 1',
    street2: 'Adres satırı 2',
    city: 'İstanbul',           // İl
    district: 'Kadıköy',        // İlçe
    postalCode: '34700',
    country: 'TR',
    phone: '05551234567',
    email: 'alici@example.com',
    taxId: '1234567890',         // Vergi numarası
);
```

### Package

[](#package)

```
new Package(
    weight: 2.5,       // KG (metric default)
    length: 30,        // CM
    width: 20,         // CM
    height: 15,        // CM
    desi: 3,           // Volumetric weight (L*W*H/3000)
    quantity: 1,
    description: 'Elektronik ürün',
);
```

### ShipmentStatus Enum

[](#shipmentstatus-enum)

```
PRE_TRANSIT      → Kayıt alındı
PICKED_UP        → Kabul edildi
IN_TRANSIT       → Aktarmada / Şubede
OUT_FOR_DELIVERY → Dağıtımda
DELIVERED        → Teslim edildi
CANCELLED        → İptal edildi
RETURNED         → İade
UNKNOWN          → Bilinmiyor

```

Key Concepts for Turkish Carriers
---------------------------------

[](#key-concepts-for-turkish-carriers)

- **Desi**: Volumetric weight = (L x W x H) / 3000. First-class field on Package.
- **District (İlçe)**: Required by all Turkish carriers. Maps to `Address::$district`.
- **Barcode**: Turkish carriers return a barcode string on shipment creation.
- **PaymentType**: Sender/receiver pays. Standard in Turkish e-commerce.
- **COD (Kapıda Ödeme)**: Cash on delivery with `cashOnDelivery` flag + `codAmount`.

Testing
-------

[](#testing)

```
# Run tests
vendor/bin/pest

# Static analysis
vendor/bin/phpstan analyse
```

License
-------

[](#license)

MIT

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance98

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity39

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.

###  Release Activity

Cadence

Every ~70 days

Total

3

Last Release

12d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/36dffe883e88aeef07c26067af3d6a7eda1c2a81f1ae45fdd430b721665131da?d=identicon)[Mobius Studio](/maintainers/Mobius%20Studio)

---

Top Contributors

[![tcgunel](https://avatars.githubusercontent.com/u/3923425?v=4)](https://github.com/tcgunel "tcgunel (5 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tcgunel-omniship-common/health.svg)

```
[![Health](https://phpackages.com/badges/tcgunel-omniship-common/health.svg)](https://phpackages.com/packages/tcgunel-omniship-common)
```

###  Alternatives

[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

86337.5k](/packages/flow-php-flow)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k19](/packages/tempest-framework)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

36826.2k2](/packages/telnyx-telnyx-php)[cakephp/cakephp

The CakePHP framework

8.9k20.0M1.8k](/packages/cakephp-cakephp)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k6.0M774](/packages/sylius-sylius)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)

PHPackages © 2026

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