PHPackages                             4port/ocean-tracking - 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. 4port/ocean-tracking

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

4port/ocean-tracking
====================

V1.0.5(6mo ago)011PHPPHP ^8.0

Since Apr 30Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/AndyMoxq/four-port)[ Packagist](https://packagist.org/packages/4port/ocean-tracking)[ RSS](/packages/4port-ocean-tracking/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)DependenciesVersions (5)Used By (0)

Ocean Tracking Laravel Package
==============================

[](#ocean-tracking-laravel-package)

Ocean Tracking 是一个轻量级的 Laravel 扩展包，用于集成外部 API 并跟踪国际海运物流状态。适用于需要追踪提单号、箱号、多段运输信息的跨境业务系统。

📦 安装 Installation
-----------------

[](#-安装-installation)

> 适配 Laravel 8.x 及以上版本

推荐使用本地路径方式安装：

```
composer require 4port/ocean-tracking
```

⚙️ 配置 Configuration
-------------------

[](#️-配置-configuration)

发布配置文件到主项目：

```
php artisan vendor:publish --tag=ocean-tracking-config
```

在 `config/ocean-tracking.php` 中配置：

```
return [
    // 使用 .env 中的配置自动初始化
    'baseUrl' => env('OCEAN_TRACKING_BASE_URL', 'https://api.example.com'),
    'app_id' => env('OCEAN_TRACKING_COMPANYID','0000'),
    'secret' => env('OCEAN_TRACKING_SECRET','YOUR-SECRET'),
];
```

🧬 数据库迁移 Migration
-----------------

[](#-数据库迁移-migration)

执行包内迁移文件：

```
php artisan migrate
```

如需发布迁移文件自行修改：

```
php artisan vendor:publish --tag=ocean-tracking-migrations
```

🚀 使用方式 Usage
------------

[](#-使用方式-usage)

> 所有请求类均提供 `fetch()` 方法作为统一入口，内部完成参数校验、请求发送及响应解析处理。

### 📝 示例一：注册追踪信息

[](#-示例一注册追踪信息)

```
use Tracking\Ocean\Request\SubscribeRequest;
use Tracking\Ocean\Traits\UpdateOceanTrackingTrait;

try {
    $request = new SubscribeRequest;

    $body = [
        'carrierCode' => 'HMM',
        'billNo' => 'NBOZ0Y012345',
        'portCode' => 'CNNGB',
        'dataType' => [
            "PORT",
            "CARRIER"
        ]
    ];

    $res = $request->setBody($body)->fetch();

    // 或者简易订阅（只获取海运数据）
    // $res = $request -> setTracking('HMM','NBOZ0Y012345')->fetch();

    // 调试响应数据
    // var_dump($res->getData());

    // 使用 UpdateOceanTrackingTrait 将响应数据写入数据库
    $tracking = $this->updateSubscribeData($res->getData());

    dump($tracking->toArray());

} catch (\Throwable $th) {
    var_dump($th->getMessage());
}
```

> 该示例演示如何注册一个新的追踪信息，向外部接口订阅物流状态更新，并将返回的数据保存到本地数据库。

### 📦 示例二：获取追踪信息

[](#-示例二获取追踪信息)

```
use Tracking\Ocean\Request\GetTrackingRequest;
use Tracking\Ocean\Models\OceanTracking;

try {
    $subscriptionId = OceanTracking::firstOrFail()->subscription_id;

    $request = new GetTrackingRequest();
    $request->setSubscriptionId($subscriptionId);
    $res = $request->fetch();

    // 自动更新主表、航程、箱信息及状态节点
    $tk = $this->updateOceanTracking($res->getData());

    dump($tk->toArray());
} catch (\Throwable $th) {
    $this->error($th->getMessage());
}
```

> 该示例展示如何根据订阅 ID 拉取最新的追踪信息，并同步更新本地数据库中的相关记录。

### 🔁 示例三：自动同步追踪数据（Webhook）

[](#-示例三自动同步追踪数据webhook)

你可以创建一个 webhook 接口用于接收来自平台的箱动态推送，并自动保存更新：

```
use Tracking\Ocean\Traits\UpdateOceanTrackingTrait;

$this->updateOceanTracking($res->getData());
```

平台推送示例：

```
POST https://your-domain.com/api/ocean-tracking
```

将自动更新主表、航程、箱信息及状态节点，无需额外处理。

> 该示例说明如何通过 webhook 接收平台主动推送的物流状态变更，实现自动同步和持久化，极大简化数据维护工作。

📡 API 对接 API Integration
------------------------

[](#-api-对接-api-integration)

本包默认支持以下功能：

- 提单号和箱号订阅及追踪；
- 支持列表
- 响应字段与接口文档保持一致；
- 可通过 HTTP 客户端重写 `generateToken()` 等方法自定义接入方式；

接口文档地址：

[查看接口文档](https://tracking.4portun.com/#/application/detail?activeId=1&categoryIndex=1&subIndex=0&apiIndex=0)

📚 License
---------

[](#-license)

MIT © 2024 Andy / 4portun

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance69

Regular maintenance activity

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

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

Total

4

Last Release

181d ago

### Community

Maintainers

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

---

Top Contributors

[![AndyMoxq](https://avatars.githubusercontent.com/u/165084870?v=4)](https://github.com/AndyMoxq "AndyMoxq (6 commits)")

### Embed Badge

![Health badge](/badges/4port-ocean-tracking/health.svg)

```
[![Health](https://phpackages.com/badges/4port-ocean-tracking/health.svg)](https://phpackages.com/packages/4port-ocean-tracking)
```

###  Alternatives

[embed/embed

PHP library to retrieve page info using oembed, opengraph, etc

2.1k11.0M97](/packages/embed-embed)[sivaschenko/magento2-clean-media

Magento 2 media analysis and cleanup

96231.9k](/packages/sivaschenko-magento2-clean-media)[bagisto/bagisto-package-generator

Bagisto Package Generator

46169.9k](/packages/bagisto-bagisto-package-generator)[ynacorp/nova-swatches

A beautiful color picking field for Laravel Nova.

22291.8k1](/packages/ynacorp-nova-swatches)[marcocesarato/minifier

This class can minify HTML, Javascript and CSS

1332.4k](/packages/marcocesarato-minifier)[risan/sentiment-analysis

Sentiment analysis library for PHP.

223.5k](/packages/risan-sentiment-analysis)

PHPackages © 2026

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