README

PHP的XCover SDK

XCover SDK简化了在PHP应用程序中集成XCover API的过程。
该库基于Guzzle 7 HTTP客户端，并提供以下特性：

AuthMiddleware执行身份验证
JsonResponseMiddleware在Guzzle响应上提供方便的json方法
XCover类中的HTTP抽象
自动响应状态码验证和自定义异常类

安装

XCover SDK可在Packagist上找到，推荐通过Composer安装。

V1版本适用于PHP 7.2或更高版本（但小于8）

V2版本适用于PHP 7.4以及8.0和更高版本

composer require covergenius/xcover-php

用法

基本用法

use XCoverClient\Config;
use XCoverClient\XCover;

// Instantiate client
$client = new XCover(new Config([
  'baseUrl' => env('BASE_URL'),
  'apiPrefix' => env('API_PREFIX'),
  'apiKey' => env('API_KEY'),
  'apiSecret' => env('API_SECRET'),
  'partner' => env('PARTNER_CODE'),
]));

// Quote request
$quoteResponse = $client->createQuote(
    [
        'request' => [
            [
                'policy_type' => 'event_ticket_protection', 
                'policy_type_version' => 1, 
                'policy_start_date' => '2019-12-01T17:59:00.831+00:00', 
                'event_datetime' => '2019-12-25T21:00:00+00:00', 
                'event_name' => 'Ariana Grande', 
                'event_location' => 'The O2', 
                'number_of_tickets' => 2, 
                'total_ticket_price' => 100, 
                'resale_ticket' => false, 
                'event_country' => 'GB' 
            ] 
        ], 
        'currency' => 'GBP',
        'customer_country' => 'GB',
        'customer_region' => 'London',
        'customer_language' => 'en' 
    ]
);
$quotePackage = $quoteResponse->json();


// Quote package array will contain all information required to display the insurance offering
echo $quotePackage['id']; // 'JWFFM-M3W3Y-INS'
echo $quotePackage['total_price']; // 5.00
echo $quotePackage['quotes'][0]['price']; // 5.00
echo $quotePackage['quotes'][0]['tax']['total_tax']; // 1.00
echo $quotePackage['quotes'][0]['tax']['total_tax_formatted']; // '£ 1.00'
echo $quotePackage['quotes'][0]['content']['title']; // 'Ticket Protection'
echo $quotePackage['quotes'][0]['content']['description']; // 'Covers the purchase cost of tickets (up to a maximum of £500) if you are unable to attend a booked event as result of an unexpected circumstance.'
echo $quotePackage['quotes'][0]['pds_url']; // 'https://xcover.com/en/pds/JWFFM-M3W3Y-INS?policy_type=event_ticket_protection_v1'


// To report insurance booking
echo $quotePackage['quotes'][0]['id']; // '40e9859d-9a2c-47fb-a0a1-5d121fc68fdd'
$bookingResponse = $client->createBooking($quotePackage['id'],
    [
        'quotes' => [
            [
                 'id' => '40e9859d-9a2c-47fb-a0a1-5d121fc68fdd',
            ]
        ],
        'policyholder' => [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'email' => 'john.doe@gmail.com',
            'age' => 30,
            'country' => 'GB'
        ]
]
);

// Booking has the same id as quote package and a similar structure
$booking = $bookingResponse->json();

echo $booking['id']; // 'JWFFM-M3W3Y-INS'
echo $booking['status']; // 'CONFIRMED'
echo $booking['total_price']; // 5.00

请参阅tests/XCoverTest.php文件以获取更多示例。

XCover类提供了XCover API文档中列出的所有操作的方法。

自定义Guzzle客户端

要自定义Guzzle配置，您可以在XCover构造函数中传递自定义客户端实例。

Guzzle 6客户端实例是不可变的，因此您需要事先准备好它并添加所有必需的配置选项，例如

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use XCoverClient\Config;
use XCoverClient\Middleware\AuthMiddleware;
use XCoverClient\Middleware\JsonResponseMiddleware;
use XCoverClient\XCover;


// Add XCover mandatory middlewares
$handlerStack = HandlerStack::create();
$handlerStack->push(
  new AuthMiddleware([
      'apiKey' => $this->config->apiKey(),
      'apiSecret' => $this->config->apiSecret(),
  ]),
  'auth'
);
$handlerStack->push(new JsonResponseMiddleware, 'json_response');

// You can add your custom middlewares here      

// You can add your custom options to the Guzzle's Client constructor below
$client =  new Client([
  'handler' => $handlerStack,
  'headers' => [
      'Content-Type' => 'application/json',
      'X-Api-Key' => $this->config->apiKey(),
  ],
]);

// Now pass it to XCover constructor as second argument
$client = new XCover(new Config([
  'baseUrl' => env('BASE_URL'),
  'apiPrefix' => env('API_PREFIX'),
  'apiKey' => env('API_KEY'),
  'apiSecret' => env('API_SECRET'),
  'partner' => env('PARTNER_CODE'),
]), $client);

也可以扩展XCover类并重写createDefaultClient函数。

待办事项

我们将在未来的版本中添加一些特性

使用Guzzle的承诺进行异步调用
断路器中间件
自带的HTTP客户端

测试

PHPUnit和PHP-VCR用于运行测试。

每次推送和拉取请求都会运行测试。

运行以下命令以运行测试

composer test

代码风格

PHP_CodeSniffer用于编码标准。我们目前遵循PSR-1和PSR-2作为标准。

每次推送和拉取请求都会运行lint检查。

运行以下命令以检查任何代码风格问题。

composer lint

您可以在phpcs.xml中查看php-cs规则。

静态分析

PHPStan用于代码的静态分析。PHPStan是一个PHP静态分析工具。PHPStan专注于在运行代码之前发现错误。它甚至在你为代码编写测试之前就能捕获整个类别的错误。

每次推送和拉取请求都会运行静态分析

运行以下命令以使用PHPStan检查代码

composer analyse

变更日志

您可以在CHANGELOG.md中查看变更日志

安全性

您可以在SECURITY.md中查看安全策略

许可

您可以在LICENSE中查看许可信息

covergenius / xcover-php

维护者

详情