README

一个用于使用 SkynetCourier API 的 Laravel 扩展包。

安装

使用 composer 安装此包

composer require claassenmarius/laravel-skynet

使用方法

将以下环境变量添加到您的 .env 文件中，并添加您的 Skynet 账户用户名、密码、系统 ID 和账户号码。

SKYNET_ACCOUNT_USERNAME=
SKYNET_ACCOUNT_PASSWORD=
SKYNET_SYSTEM_ID=
SKYNET_ACCOUNT_NUMBER=

您可以通过以下方式获取 Claassenmarius\LaravelSkynet\Skynet 的实例：

类型提示 / 依赖注入

当在方法中类型提示 Skynet 时，Laravel 会自动从 IOC 容器中为您解析。

use Claassenmarius\LaravelSkynet\Skynet;

class QuoteController extends Controller
{
    public function __invoke(Skynet $skynet)
    {
        $response = $skynet->quote(...);
        
        // do somethin with the $response
    }    
}

外观

您可以使用 Skynet 外观。

use Claassenmarius\LaravelSkynet\Facades\Skynet;

class QuoteController extends Controller
{
    public function __invoke()
    {
        $response = Skynet::quote(...);
        
        // do somethin with the $response
    }   
}

手动从 IOC 容器中解析

use Claassenmarius\LaravelSkynet\Skynet;

class QuoteController extends Controller
{
    public function __invoke()
    {
        $skynet = app()->make(Skynet::class);
        
        $response = $skynet->quote(...);
        
        // do somethin with the $response
    }   
}

手动实例化

如果您打算在整个项目中手动实例化 Skynet，则不需要将您的 Skynet 凭证添加到 .env 文件中。相反，将您的凭证传递给构造函数。

use Claassenmarius\LaravelSkynet\Skynet;

class QuoteController extends Controller
{
    public function __invoke()
    {
        $skynet = new Skynet(
          'skynet_username',
          'skynet_password',
          'skynet_system_id',
          'skynet_account_number'
        );
        
        $response = $skynet->quote(...);
        
        // do somethin with the $response
    }
}

以下方法可用于获取安全令牌、验证郊区/邮政编码组合、获取郊区邮政编码列表、获取包裹报价、获取两个地点之间的预计时间、生成运单、获取运单 POD 图像和跟踪运单。每个方法都返回一个新的 Illuminate\Http\Client\Response，它提供了用于检查响应的方法。

获取安全令牌

$response = $skynet->securityToken();

验证郊区/邮政编码组合

$response = $skynet->validateSuburbAndPostalCode([
    'suburb' => 'Brackenfell',
    'postal-code' => '7560'
]);

获取郊区邮政编码列表

$response = $skynet->postalCodesFromSuburb('Brackenfell');

获取包裹报价

$response = $skynet->quote([
    'collect-city' => 'Brackenfell',
    'deliver-city' => 'Stellenbosch',
    'deliver-postcode' => '7600',
    'service-type' => 'ON1',
    'insurance-type' => '1',
    'parcel-insurance' => '0',    
    'parcel-length' => 10, //cm
    'parcel-width' => 20, // cm
    'parcel-height' => 30, //cm
    'parcel-weight' => 20 //kg
]);

获取两个地点之间的预计时间

$response = $skynet->deliveryETA([
    'from-suburb' => 'Brackenfell',
    'from-postcode' => '7560',
    'to-suburb' => 'Stellenbosch',
    'to-postcode' => '7600',
    'service-type' => 'ON1'
]);

生成运单

$response = $skynet->createWaybill([
    "customer-reference" => "Customer Reference",
    "GenerateWaybillNumber" => true,
    "service-type" => "ON1",
    "collection-date" => "2021-06-26",
    "from-address-1" => "3 Janie Street, Ferndale, Brackenfell",
    "from-suburb" => "Brackenfell",
    "from-postcode" => "7560",
    "to-address-1" => "15 Verreweide Street, Universiteitsoord, Stellenbosch",
    "to-suburb" => "Stellenbosch",
    "to-postcode" => "7600",
    "insurance-type" => "1",
    "insurance-amount" => "0",
    "security" => "N",
    "parcel-number" => "1",
    "parcel-length" => 10,
    "parcel-width" => 20,
    "parcel-height" => 30,
    "parcel-weight" => 10,
    "parcel-reference" => "12345",
    "offsite-collection" => true
]);

获取运单 POD 图像

$response = $skynet->waybillPOD('your-waybill-number');

跟踪运单

$response = $skynet->trackWaybill('your-waybill-number');

响应

Illuminate\Http\Client\Response 提供以下方法来检查响应。

获取响应体作为字符串

$securityToken = $response->body(); 
// "{"SecurityToken":"2_f77e4922-1407-485e-a0fa-4fdd5c29e9ca"}" 

获取 JSON 解码后的响应体作为数组或标量值（如果传递了 $key）

$securityToken = $response->json($key); 
// ["SecurityToken" => "2_c767aa41-bca8-4084-82a0-69d8e27fba2c"] 

获取 JSON 解码后的响应体作为对象。

$securityToken = $response->object(); 
// { +"SecurityToken": "2_c767aa41-bca8-4084-82a0-69d8e27fba2c" }

获取 JSON 解码后的响应体作为集合。

$securityToken = $response->collect($key); 

获取响应中的头。

$header = $response->header($header); 
// "application/json; charset=utf-8"

获取响应中的所有头。

$headers = $response->headers(); 
// Return an array of all headers

获取响应的状态码。

$headers = $response->status(); 
// 200

确定请求是否成功（状态码 >= 200 且 < 300）

$headers = $response->successful(); 
// true

确定响应代码是否为 "OK"。 （状态码 === 200）

$headers = $response->ok(); 
// true

确定是否发生服务器错误。 （状态码 >= 500）

$headers = $response->serverError(); 
// false

确定是否发生客户端或服务器错误。

$headers = $response->failed(); 
// false

您可以在 Laravel 文档中查看有关 Illuminate\Http\Client\Response 提供的方法的更多信息。

异常处理

此包在幕后使用 Laravel 的 Http Client，它不会在客户端或服务器错误（来自服务器的 400 和 500 级响应）上抛出异常。您可以使用 successful、clientError 或 serverError 方法确定是否返回了这些错误之一。

如果您有一个响应实例，并且希望在响应状态码指示客户端或服务器错误时抛出 Illuminate\Http\Client\RequestException 实例，您可以使用 throw 方法。

response = $skynet->quote(...);

if($response->failed()) {
// Throw an exception if a client or server error occurred...
  $response->throw();
}

测试

composer test

变更日志

请参阅变更日志获取有关最近更改的更多信息。

贡献

请参阅贡献指南获取详细信息。

安全

如果您发现任何安全相关的问题，请发送电子邮件至marius.claassen@outlook.com而不是使用问题跟踪器。

许可

MIT 许可证（MIT）。有关更多信息，请参阅许可文件。