PHPackages                             overbeck/logistics - 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. overbeck/logistics

ActiveLibrary

overbeck/logistics
==================

A quick library for querying express logistics information.

1.0.7(5y ago)715MITPHPPHP >=7.2CI failing

Since Aug 2Pushed 5y ago1 watchersCompare

[ Source](https://github.com/shuqingzai/logistics)[ Packagist](https://packagist.org/packages/overbeck/logistics)[ Docs](https://github.com/shuqingzai/logistics)[ RSS](/packages/overbeck-logistics/feed)WikiDiscussions master Synced 6d ago

READMEChangelog (8)Dependencies (4)Versions (12)Used By (0)

 logistics
===========

[](#-logistics-)

 A quick library for querying express logistics information.

[![Build Status](https://camo.githubusercontent.com/256bb1d34452d6b461b3533f653335b00beb638c7bc88384f83faa69acf6dc49/68747470733a2f2f7472617669732d63692e6f72672f73687571696e677a61692f6c6f676973746963732e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/shuqingzai/logistics)[![StyleCI build status](https://camo.githubusercontent.com/275302d193e160b455dcf95d9b5622d8f812a5b306c80d68515ac5826cbf7f2f/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3238333133323434382f736869656c64)](https://camo.githubusercontent.com/275302d193e160b455dcf95d9b5622d8f812a5b306c80d68515ac5826cbf7f2f/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3238333133323434382f736869656c64)[![Latest Stable Version](https://camo.githubusercontent.com/4851af11f0e2d87276e8596677cd38e356b60bc5da1bcd01c4daf668d3f989c2/68747470733a2f2f706f7365722e707567782e6f72672f6f7665726265636b2f6c6f676973746963732f76)](//packagist.org/packages/overbeck/logistics)[![Total Downloads](https://camo.githubusercontent.com/056509e86a00854cbac410b476c2f21406a10dd43790bc976af9ebb50d8d0255/68747470733a2f2f706f7365722e707567782e6f72672f6f7665726265636b2f6c6f676973746963732f646f776e6c6f616473)](//packagist.org/packages/overbeck/logistics)[![Latest Unstable Version](https://camo.githubusercontent.com/a3273790ae719a84f6b901de18351552fcc9c07c01a79850e1a40a558dd6260b/68747470733a2f2f706f7365722e707567782e6f72672f6f7665726265636b2f6c6f676973746963732f762f756e737461626c65)](//packagist.org/packages/overbeck/logistics)[![License](https://camo.githubusercontent.com/1c0e8f1ee2042d3d2d89e88cff21fb625772ff83498a5e348ca7962e6e4f2830/68747470733a2f2f706f7365722e707567782e6f72672f6f7665726265636b2f6c6f676973746963732f6c6963656e7365)](//packagist.org/packages/overbeck/logistics)[![composer.lock](https://camo.githubusercontent.com/3a4145aea4b15895aca570fba87654ae2494dd01228c023bbb24b930474f1420/68747470733a2f2f706f7365722e707567782e6f72672f6f7665726265636b2f6c6f676973746963732f636f6d706f7365726c6f636b)](//packagist.org/packages/overbeck/logistics)[![.gitattributes](https://camo.githubusercontent.com/d99efa2f6efed0cfbf939d4e128cf0964e0c62ad2ece296cc0aa564b138c7491/68747470733a2f2f706f7365722e707567782e6f72672f6f7665726265636b2f6c6f676973746963732f67697461747472696275746573)](//packagist.org/packages/overbeck/logistics)

[![Anurag's github stats](https://camo.githubusercontent.com/adebeb5ea7e95c9ddc9d59e997f2b277fc94218a924e8650172a5f9c1fdfde37/68747470733a2f2f6769746875622d726561646d652d73746174732e76657263656c2e6170702f6170693f757365726e616d653d73687571696e677a61692673686f775f69636f6e733d74727565267468656d653d636f62616c74)](https://camo.githubusercontent.com/adebeb5ea7e95c9ddc9d59e997f2b277fc94218a924e8650172a5f9c1fdfde37/68747470733a2f2f6769746875622d726561646d652d73746174732e76657263656c2e6170702f6170693f757365726e616d653d73687571696e677a61692673686f775f69636f6e733d74727565267468656d653d636f62616c74)

简介
--

[](#简介)

**用于快捷查询快递物流信息，返回统一格式，无需担心字段格式不一致导致的各种问题**

支持平台
----

[](#支持平台)

目前支持以下平台

- [快递100](https://www.kuaidi100.com/)
- [快递鸟](https://www.kdniao.com/)
- [聚合数据](https://www.juhe.cn/docs/api/id/43)

环境依赖
----

[](#环境依赖)

- PHP >= 7.2
- json拓展
- openssl拓展
- simplexml拓展

安装
--

[](#安装)

```
$ composer require overbeck/logistics -vvv
```

使用
--

[](#使用)

### 配置与使用

[](#配置与使用)

```
require __DIR__ . '/vendor/autoload.php';

use Overbeck\Logistics\Logistics;

$config = [
    /*
     * 全局 http
     * 请求配置 参考 https://guzzle-cn.readthedocs.io/zh_CN/latest/request-options.html
     */
    'http'         => [
        'timeout'         => 5.0,
        'connect_timeout' => 5.0
    ],

    /*
     * 默认网关配置，如果设置此项，则只会使用该网关请求，否则会循环 gateways 调用请求不同的网关
     */
    'default'      => '',

    /*
     * 禁用网关，默认情况下会循环调用  gateways 下的所有可用网关，你可以添加网关名称到此禁用
     */
    'disable'      => [],

    /*
     * 网关配置
     */
    'gateways'     => [
        'kuaidi100' => [
            'key'      => '12124564561', // key
            'customer' => 'sahdkjsadjashuidhasdbak', // customer
            /*
             * 可以单独为指定的网关配置 http 请求信息，未设置则读取全局
             */
            'http'         => [
                'timeout'         => 15.0,
                'connect_timeout' => 15.0
            ],
        ],
        'kdniao'    => [
            'appKey'      => '456das12-dda-s87-d9a-1d2a1-o-p9', // appKey
            'EBusinessID' => '123456789', // EBusinessID
        ],
        'juhe'=>[
            'appKey'      => '4p5as1d21d564a56d12ad165a4d6', // appKey
        ]
        // ...
    ],

    /*
     * 格外配置物流公司列表
     */
    'company_file' => []
];
$logistics = new Logistics($config);
$res       = $logistics->query('123456789','顺丰速运');
```

### 快速使用示例

[](#快速使用示例)

```
// 提供 query() 函数即时查询物流信息
$logistics->query(string $logisticNumber, ?string $company = null, ?string $phone = null, $gateways = []): array
// 示例
$logistics->query('123456789'); // 仅用快递单号查询，不清楚快递公司时可用
$logistics->query('123456789','圆通速递'); // 锁定快递公司，更快速的查询
// 如果是 顺丰速运 的物流单号查询必须传递寄件人手机号
$logistics->query('123456789','顺丰速运','13800138000');
```

### 物流公司

[](#物流公司)

如果传入物流公司名称，可以快速锁定物流单号，无需额外的`http`请求第三方网关获取，减少开销

默认提供 `/vendor/overbeck/logistics/src/config/company.php` 物流公司列表文件，已包含一些常用的物流公司与物流公司`code` ,允许用户自定义配置文件或动态设置

#### 文件配置物流公司

[](#文件配置物流公司)

在 `congfig.company_file` 设置文件路径，支持配置多个文件，并且支持两种格式 ( `php`、`json` )

```
// 格外配置物流公司列表文件
'company_file' => [__DIR__ . '/company1.php',__DIR__ . '/company1.json']
```

每种文件格式示例

**php**

`php` 格式文件是直接使用 `include` 关键字引入，所以必须使用`return` 关键字返回数组

`company1.php` 内容

```
return [
    [
        'name' => '顺丰速运',
        'code' =>
            [
                'aliyun'    => 'SFEXPRESS',
                'juhe'      => 'sf',
                'kuaidi100' => 'shunfeng',
                'kdniao'    => 'SF',
            ],
    ],
    [
        'name' => '申通快递',
        'code' =>
            [
                'aliyun'    => 'STO',
                'juhe'      => 'sto',
                'kuaidi100' => 'shentong',
                'kdniao'    => 'STO',
            ],
    ]
];
```

**json**

`company1.json` 文件内容

```
[
    {
        "name": "顺丰速运1",
        "code": {
            "aliyun": "SFEXPRESS",
            "juhe": "sf",
            "kuaidi100": "shunfeng",
            "kdniao": "SF"
        }
    },
    {
        "name": "申通快递2",
        "code": {
            "aliyun": "STO",
            "juhe": "sto",
            "kuaidi100": "shentong",
            "kdniao": "STO"
        }
    }
]
```

#### 动态配置物流公司

[](#动态配置物流公司)

当然，你也可以动态直接传入二维数组而不需要额外创建物流公司配置文件

```
$logistics->setCompanyList(array $companyList);
```

**注意：不管你是直接传入数据还是配置文件，都需要保持与上述示例中的数据结构一致，如果物流公司名称和已有的物流公司名称(`name`)一样，则会替代已有的物流公司**

#### 获取物流公司列表

[](#获取物流公司列表)

你可以获取所有的物流公司列表

```
$logistics->getCompanyList();
```

也可以获取默认的物流公司列表

```
$logistics->getDefaultCompanyList();
```

### 可用网关

[](#可用网关)

一般情况下，可用网关是在配置文件中读取，你也可以直接传递第三个参数指定网关

```
$logistics->query('123456789','申通快递', null, 'kuaidi100'); // 指定单个网关的时，可以直接传递字符串
$logistics->query('123456789','申通快递', null, ['kuaidi100', 'kuaidiniao']);
```

**注意：如果传递的网关不可用，会抛出 `\Overbeck\Logistics\Exceptions\InvalidArgumentException` 异常**

### 禁用网关

[](#禁用网关)

如果你配置的网关很多，你也可以临时禁用某些网关，只需要在 `config.disable` 配置需要禁用的网关即可

```
 // 禁用网关，默认情况下会循环调用  gateways 下的所有可用网关，你可以添加网关名称到此禁用
 'disable'      => [],
```

### 默认网关

[](#默认网关)

当你只是使用一个网关时，可以直接配置默认网关即可

**注意：如果配置了默认网关，那么其他网关都会失效，只有默认网关会有效**

```
 // 默认配置，如果设置此项，就只会使用该网关请求，否则会循环 gateways 调用请求不同的网关
 'default'      => 'kuaidi100',
```

响应结果
----

[](#响应结果)

统一返回一个二维数组，数组中的值是每个网关的结果集，它是 `\Overbeck\Logistics\Supports\Collection` 结果集对象

```
 [
  "kuaidi100" => {
      [
          "gateway" => "kuaidi100"
          "status" => "success" // 网关请求成功 success 发生异常 failure
          "result" => [ // 查询结果
              "code" => 1 // 1 表示有结果 list会有数据 0 是查无结果
              "status" => 4 // 统一的状态返回
              "status_name" => "已签收" // 状态名称描述
              "company_code" => "youzhengbk" // 快递公司code
              "company_name" => "邮政快递包裹" // 快递公司名称
              "tracking_number" => "1178858799304" // 快递单号
              "list" => [
                  // ...
                  [
                      "context" => "离开【中国邮政集团公司贵州省石阡县寄递事业部本部揽投部】,下一站【贵州石阡县中心】"
                      "date_time" => "2020-07-27 17:46:27"
                  ],
                  [
                      "context" => "铜仁市 【中国邮政集团公司贵州省石阡县寄递事业部本部揽投部】已收件,揽投员:胡俊,电话:13758785985"
                      "date_time" => "2020-07-27 17:26:49"
                  ],
                 // ...
              ],
              "original_data" => "{...}" // json字符串 响应原数据信息
          ]
  	  ]
  }
  "kdniao" => {
    [
      "gateway" => "kdniao"
      "status" => "failure"
      "exception" => \Overbeck\Logistics\Exceptions\Exceptions // 错误响应对象
    ]
  }
     // ...
]
```

**读取信息**

```
$res = $logistics->query('123456789','顺丰速运');

/** @var \Overbeck\Logistics\Supports\Collection $kd */
$kd  = $res['kuaidi100'];
echo $kd->get('status'); // 获取网关状态
echo $kd100->get('result.status'); // 获取快递状态
echo $kd100->get('result.status_name'); // 获取快递状态名称
dump($kd->get('result.list')); // 获取快递信息列表
// ....
```

**`result.status` 说明**

值（status）名称（status\_name）解析99快递查询异常请求发送成功，但是业务查询失败，具体原因查看 `original_data` 的原数据1快递收件(揽件)货物已由快递公司揽收2运输中货物处于运输过程中3派件中货物正在进行派件4已签收正常签收5疑难件网关无法解析或解析错误的状态，最好需要人工核实6退件签收货物退回发货人并签收7拒签收件人明确拒收8退回货物正处于返回发货人的途中9超时件货物派送超时10派送失败货物派送失败，具体原因联系快递公司异常处理
----

[](#异常处理)

系统定义三个异常类

`\Overbeck\Logistics\Exceptions\InvalidArgumentException` 用于处理参数错误异常

`\Overbeck\Logistics\Exceptions\GatewayErrorException` 用于处理请求网关响应数据错误

`\Overbeck\Logistics\Exceptions\GatewayAvailableException` 当所有可用网关都不能使用时，抛出该异常

`\Overbeck\Logistics\Exceptions\GatewayErrorException` 和 `\Overbeck\Logistics\Exceptions\GatewayAvailableException` 都提供了一个 `getResults()` 函数获取远程请求返回的信息

`\Overbeck\Logistics\Exceptions\GatewayAvailableException` 还实现 `Overbeck\Logistics\Interfaces\GatewayAvailableInterface` 接口，提供几个有用的函数

Laravel 应用
----------

[](#laravel-应用)

### 1. 注册服务

[](#1-注册服务)

在 `config/app.php` 注册 **ServiceProvider** 和 **Facade** ( `Laravel 5.5 +` 无需手动注册，可跳过此步)

```
'providers' => [
    // ...
    Overbeck\Logistics\Laravel\ServiceProvider::class,
],
'aliases' => [
    // ...
    'Logistics' => Overbeck\Logistics\Laravel\Logistics::class,
],
```

### 2. 发布配置文件

[](#2-发布配置文件)

```
php artisan vendor:publish --provider="Overbeck\Logistics\Laravel\ServiceProvider"
```

修改应用根目录下的 `config/logistics.php` 中对应的参数即可。

### 3. 门面

[](#3-门面)

**门面类是 `\Overbeck\Logistics\Laravel\Logistics`**

示例

```