README

PHP HTTP客户端库，用于与JNE网站通信。此库可用于检索JNE的运输运费和所有可用运输地点。

目录

• 依赖项
• 安装
• 基本用法
• 搜索起点
• 搜索终点
• 获取运输选项
  • 查找或创建起点位置
  • 查找或创建终点位置
  • 创建重量实例
  • 创建包裹实例
  • 列出所有可用选项

依赖项

此包依赖于以下库以工作

• Guzzle
• Illuminate Support
• Symfony DomCrawler组件
• Symfony CssSelector组件

如果您使用Composer安装此包，所有上述依赖项将自动下载。

安装

要使用Composer安装此库，请在项目目录中运行以下命令

composer require risan/jne

或者您也可以将risan\jne包添加到您的composer.json文件中，如下所示

"require": {
  "risan/jne": "~1.1"
}

然后不要忘记运行以下命令来安装此库

composer install

基本用法

以下是如何使用此库的一些基本示例

<?php
// Include autoloder file.
require 'vendor/autoload.php';

// Create a new instance Jne\Jne.
$jne = new Jne\Jne();

// Search for origin city and get the first mathced item.
$bandung = $jne->searchOrigin('Bandung')->first();

// Search for destination city ang get the first matched item.
$depok = $jne->searchDestination('Depok')->first();

// Create a package instance.
// From bandung to depok 10 Kilograms package.
$myPackage = new Jne\Package($origin, $destination, Jne\Weight::fromKilograms(10));

// Get delivery options for $myPackage.
// @return Jne\Collections\DeliveryOptionCollection
$deliveryOptions = $jne->deliveryOptions($myPackage);

搜索起点

要搜索可用的起点城市或位置，我们可以使用Jne\Jne类拥有的searchOrigin()方法。我们只需要传递一个字符串的$query参数。

$jne->searchOrigin(string $query);

此方法将对jne.co.id网站执行HTTP请求，以搜索所有与给定$query匹配的可用起点位置。

在成功的情况下，此方法将返回一个Jne\Collections\LocationCollection类的实例，其中包含一组Jne\Location实例。本身LocationCollection是Illuminate\Support\Collection的子类，因此我们可以利用Laravel的集合的丰富功能。

例如，我们可以找到所有匹配单词bandar的可用起点位置，如下所示

$jne = new Jne\Jne();

$origins = $jne->searchOrigin('bandar');

我们可以使用toArray()方法将$origin转换为数组，并看到它包含几个Jne\Location实例

print_r($origins->toArray());

Array
(
  [0] => Jne\Location Object
    (
      [name:protected] => BANDAR SRI BENTAN, KAB.BINTAN
      [code:protected] => VE5KMTAxMDA=
    )

  [1] => Jne\Location Object
    (
      [name:protected] => BANDAR,SIMALUNGUN
      [code:protected] => TUVTMjA2MDE=
    )

  [2] => Jne\Location Object
    (
      [name:protected] => BANDARLAMPUNG
      [code:protected] => VEtHMTAwMDA=
    )
)

搜索终点

要搜索所有可用的目的地城市或位置，我们可以使用searchDestination()方法。其用法与searchOrigin()方法非常相似

$jne->searchDestination(string $query);

此方法也将对jne.co.id网站执行HTTP请求，以搜索所有与给定$query匹配的可用目的地位置。

此方法也将返回一个Jne\Collections\LocationCollection类的实例。

例如，如果我们想搜索匹配purwodadi的目的地位置，我们可以这样做

$jne = new Jne\Jne();

$destinations = $jne->searchDestination('purwodadi');

如果我们打印出$destinations结果，我们将得到以下输出

Array
(
  [0] => Jne\Location Object
    (
        [name:protected] => PURWODADI,KAB.GROBOGAN
        [code:protected] => U1JHMjExMDA=
    )

  [1] => Jne\Location Object
    (
        [name:protected] => PURWODADI,MUARA BELITI BARU
        [code:protected] => UExNMTAzMTI=
    )

  [2] => Jne\Location Object
    (
        [name:protected] => PURWODADI,PASURUAN
        [code:protected] => UEROMTAwMTU=
    )

  [3] => Jne\Location Object
    (
        [name:protected] => PURWODADI,PURWOREJO
        [code:protected] => TUdMMTAzMDg=
    )
)

获取运输选项

使用此库，我们还可以获取JNE提供的所有可用运输选项，列出所有运费和估计的运输天数。

查找或创建起点位置

首先我们需要找到或创建包裹的起点位置，它必须是Jne\Location类的实例。要找到起点位置，我们可以使用searchOrigin()方法

// Create an instance of Jne\Jne class.
$jne = new Jne\Jne();

// Find origin locations that match `Bandung`.
$origins = $jne->searchOrigin('Bandung');

// Get the first matched location.
$bandung = $origin->first();

$bandung变量将包含以下值

Jne\Location Object
  (
    [name:protected] => BANDUNG
    [code:protected] => QkRPMTAwMDA=
  )

如果您已经知道位置代码，您也可以手动创建Jne\Location实例。这样我们就不必向JNE网站发送额外的HTTP请求

$origin = new Jne\Location(string $name, string $code);

例如，如果我们已经知道 BANDUNG 的位置代码为 QkRPMTAwMDA=，那么我们可以创建一个如下的 Jne\Location 实例

$bandung = new Jne\Location('BANDUNG', 'QkRPMTAwMDA=');

查找或创建终点位置

第二步是查找或创建包裹的目的地。要查找目的地

// Create an instance of Jne\Jne class.
$jne = new Jne\Jne();

// Find destination locations that match `Depok`.
$destinations = $jne->searchOrigin('Depok');

// Get the first matched location.
$depok = $destinations->first();

现在上面的 $depok 变量将包含以下值

Jne\Location Object
  (
    [name:protected] => DEPOK
    [code:protected] => RFBLMTAwMDA=
  )

如果你已经知道目的地的代码，你可以手动创建一个 Jne\Location 实例

$destination = new Jne\Location(string $name, string $code);

例如，如果我们已经知道目的地 DEPOK 的位置代码为 RFBLMTAwMDA=，那么我们可以这样创建它

$depok = new Jne\Location('DEPOK', 'RFBLMTAwMDA=');

创建重量实例

第三步是创建一个反映我们包裹重量的 Jne\Weight 实例。我们有几种创建 Jne\Weight 实例的方法

// Create from grams unit.
Jne\Weight::fromGrams(float $grams);

// Create from kilograms unit.
Jne\Weight::fromKilograms(float $kilograms);

// Create from pounds unit.
Jne\Weight::fromPounds(float $pounds);

例如，如果我们的包裹重量为 10 公斤，我们需要创建一个如下重量的实例

$weight = Jne\Weight::fromKilograms(10);

创建包裹实例

第四步是创建 Jne\Package 类的实例。这个实例代表我们需要交付的包裹。

$package = new Jne\Package($origin, $destination, $weight);

其中 $origin 和 $destination 都是 Jne\Location 实例的实例。而 $weight 是 Jne\Weight 类的实例。

以下是创建包裹实例的完整示例

$jne = new Jne\Jne();

// Create a origin location.
$bandung = new Jne\Location('BANDUNG', 'QkRPMTAwMDA=');

// Find a destination location.
$depok = $jne->searchDestination('DEPOK')->first();

// Create weight.
$weight = Jne\Weight::fromKilograms(10);

$package = new Jne\Package($bandung, $depok, $weight);

列出所有可用选项

最后一步是调用 deliveryOptions() 方法并传递 Jne\Package 实例来检索所有可用的配送选项

$jne = new Jne\Jne();

$jne->deliveryOptions(Jne\Package $package);

此方法将返回一个 Jne\Collections\DeliveryOptionCollection 类的实例，该实例包含一个 Jne\DeliveryOption 实例的集合。就像 LocationCollection 类一样，这个 DeliveryOptionCollection 类也是 Illuminate\Support\Collection 的子类。

例如，我们可以这样获取从 BANDUNG 到 DEPOK 的 10 公斤包裹的所有可用的配送选项

$jne = new Jne\Jne();

// Create a origin location.
$bandung = new Jne\Location('BANDUNG', 'QkRPMTAwMDA=');

// Create a destination location.
$depok = new Jne\Location('DEPOK', 'RFBLMTAwMDA=');

// Create weight.
$weight = Jne\Weight::fromKilograms(10);

// Create package.
$package = new Jne\Package($bandung, $depok, $weight);

$deliveryOptions = $jne->deliveryOptions($package);

$deliveryOptions 将包含一个 Jne\DeliveryOption 实例的集合。如果我们把 $deliveryOptions 打印到控制台，我们将得到一系列不同的配送选项

Array
(
  [0] => Jne\DeliveryOption Object
    (
      [service:protected] => OKE
      [type:protected] => Dokumen / Paket
      [tariff:protected] => 100000
      [estimatedDays:protected] => 2-3 Days
    )

  [1] => Jne\DeliveryOption Object
    (
      [service:protected] => REG
      [type:protected] => Dokumen / Paket
      [tariff:protected] => 110000
      [estimatedDays:protected] => 1-2 Days
    )
  ...