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 的承诺进行异步调用
断路器中间件
BYO HTTP 客户端

测试

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

在向存储库推送和拉取请求时运行测试。

运行以下命令以运行测试

composer test

代码风格

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

在每次推送和拉取请求时运行代码风格检查。

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

composer lint

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

静态分析

PHPStan 用于代码的静态分析。PHPStan 是 PHP 静态分析工具。PHPStan 专注于在不实际运行代码的情况下发现错误。它甚至在你为代码编写测试之前就捕捉到整个类别的错误。

在每次推送和拉取请求时运行静态分析。

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

composer analyse

变更日志

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

安全

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

许可证

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

covergenius / xcover-php

维护者

详情