PHPackages                             shippable/hub - 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. [Utility & Helpers](/categories/utility)
4. /
5. shippable/hub

ActiveLibrary[Utility & Helpers](/categories/utility)

shippable/hub
=============

Shipping Service Package for Laravel with Strategy and Adapter patterns

v1.0.7(today)115↑2900%MITPHPPHP ^8.2

Since Jun 22Pushed todayCompare

[ Source](https://github.com/linh20000/shipping-workflow)[ Packagist](https://packagist.org/packages/shippable/hub)[ RSS](/packages/shippable-hub/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (4)Versions (8)Used By (0)

wf/shipping
===========

[](#wfshipping)

Laravel Package cung cấp dịch vụ vận chuyển qua **Strategy + Adapter Pattern**, hỗ trợ GHN, GHTK và ViettelPost.

---

Cài đặt
-------

[](#cài-đặt)

### 1. Thêm local path (development)

[](#1-thêm-local-path-development)

```
// composer.json của dự án
{
    "repositories": [
        {
            "type": "path",
            "url": "../package-php/shipping",
            "options": { "symlink": true }
        }
    ],
    "require": {
        "wf/shipping": "*"
    }
}
```

```
composer require wf/shipping --ignore-platform-reqs
```

### 2. Publish config (tuỳ chọn)

[](#2-publish-config-tuỳ-chọn)

```
php artisan vendor:publish --tag=shipping-config
```

> Package sẽ tự động load config mặc định nếu bạn chưa publish. Chỉ publish khi muốn tuỳ chỉnh.

### 3. Thêm biến môi trường vào `.env`

[](#3-thêm-biến-môi-trường-vào-env)

```
# GHN
GHN_TOKEN=your-ghn-token
GHN_BASE_URL=https://dev-online-gateway.ghn.vn/shiip/public-api

# GHTK
GHTK_TOKEN=your-ghtk-token
GHTK_B2C_TOKEN=your-ghtk-b2c-token
GHTK_ENDPOINT=https://services.giaohangtietkiem.vn

# ViettelPost
VIETTELPOST_TOKEN=your-vtp-token
VIETTELPOST_ENDPOINT=https://partner.viettelpost.vn
```

---

Cách sử dụng
------------

[](#cách-sử-dụng)

Package sử dụng **Factory Pattern** để bạn có thể tuỳ ý gọi dịch vụ ở bất cứ đâu (Controller, Job, Command) mà không bị phụ thuộc vào HTTP Request.

### Cách 1 — Inject qua Constructor (Recommended)

[](#cách-1--inject-qua-constructor-recommended)

```
use Wf\Shipping\ShippingFactory;
use Wf\Shipping\DTO\StandardShippingPayload;

class OrderController extends Controller
{
    public function __construct(
        private readonly ShippingFactory $shippingFactory
    ) {}

    public function createOrder(Request $request)
    {
        $payload = StandardShippingPayload::fromArray($request->validated());

        // Bạn có thể chọn hãng vận chuyển động từ request hoặc fix cứng
        $method = $request->input('service_method', 'express'); // express, standard, fast
        $strategy = $this->shippingFactory->make($method);

        $result = $strategy->createOrder($payload);

        return response()->json($result);
    }
}
```

### Cách 2 — Resolve thủ công qua `app()`

[](#cách-2--resolve-thủ-công-qua-app)

```
use Wf\Shipping\ShippingFactory;

$factory = app(ShippingFactory::class);
$ghnStrategy = $factory->make('express');
$ghtkStrategy = $factory->make('standard');
```

### Cách 3 — Dùng trực tiếp SDK thô

[](#cách-3--dùng-trực-tiếp-sdk-thô)

```
use Wf\Shipping\GHN;
use Wf\Shipping\GHTK;
use Wf\Shipping\ViettelPost;

$ghn  = new GHN(config('shipping.ghn.token'));
$resp = $ghn->getProvince(); // array

$ghtk = new GHTK(config('shipping.ghtk.token'));
$fee  = $ghtk->caculateFee([...]); // json string

$vtp  = new ViettelPost(config('shipping.viettelpost.token'));
$provinces = $vtp->getProvice(); // json string
```

---

Cấu trúc package
----------------

[](#cấu-trúc-package)

```
src/
├── config/
│   └── shipping.php          ← Cấu hình endpoint, token, service_method
├── Contracts/
│   └── ShippingStrategyInterface.php  ← Interface chính dự án inject
├── DTO/
│   └── StandardShippingPayload.php    ← DTO chuẩn hoá payload đầu vào
├── Adapters/
│   ├── GHNAdapter.php        ← Map DTO → format GHN
│   ├── GHTKAdapter.php       ← Map DTO → format GHTK
│   └── ViettelPostAdapter.php← Map DTO → format VTP
├── Strategies/
│   ├── GHNStrategy.php       ← Xử lý logic GHN, gọi GHN SDK
│   ├── GHTKStrategy.php      ← Xử lý logic GHTK, gọi GHTK SDK
│   └── ViettelPostStrategy.php
├── GHN.php                   ← SDK gọi GHN API thật
├── GHTK.php                  ← SDK gọi GHTK API thật
├── ViettelPost.php            ← SDK gọi ViettelPost API thật
└── Providers/
    └── ShippingServiceProvider.php

```

---

Thêm hãng vận chuyển mới
------------------------

[](#thêm-hãng-vận-chuyển-mới)

1. Tạo `src/Adapters/NewCarrierAdapter.php` — map DTO sang format của hãng.
2. Tạo `src/Strategies/NewCarrierStrategy.php` — gọi SDK qua Adapter.
3. Thêm vào `ShippingServiceProvider::register()`: ```
    new NewCarrierStrategy(token: config('shipping.newcarrier.token')),
    ```
4. Thêm config vào `src/config/shipping.php`.

---

Interface cần implement
-----------------------

[](#interface-cần-implement)

```
interface ShippingStrategyInterface
{
    public function getServiceMethodName(): string;
    public function createOrder(StandardShippingPayload $payload): array;
    public function calculateFee(StandardShippingPayload $payload): array;
    public function cancelOrder(string $orderCode): array;
    public function getOrderDetail(string $orderCode): array;
    public function getProvince(): array;
    public function getDistrict(int $provinceId): array;
    public function getWard(int|string $districtId): array;
}
```

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance100

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

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 ~0 days

Total

7

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/110064975?v=4)[linh20000](/maintainers/linh20000)[@linh20000](https://github.com/linh20000)

### Embed Badge

![Health badge](/badges/shippable-hub/health.svg)

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.4k51.0M7.5k](/packages/larastan-larastan)[spatie/laravel-export

Create a static site bundle from a Laravel app

672139.5k6](/packages/spatie-laravel-export)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[calebdw/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

15104.9k4](/packages/calebdw-larastan)

PHPackages © 2026

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