unidays/unidays-php

这是与 UNiDAYS 集成的 PHP 库

维护者

详细信息

github.com/MyUNiDAYS/unidays-php

主页

源代码

问题

安装: 32,847

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 28

分支: 2

公开问题: 2

v1.2.2 2019-02-25 09:59 UTC

Requires

Requires (Dev)

MIT 4caf087fe22eb56b9b5a9b06f1ae00351bcc8274

This package is auto-updated.

Last update: 2024-09-25 23:29:30 UTC

README


Build Status

UNiDAYS PHP 库

这是与 UNiDAYS 集成的 PHP 库。它用于代码化和无代码集成。以下文档提供了实现和示例的描述。

内容

如何使用此代码？

直接跟踪

无代码验证

贡献

如何使用此代码

  • 从 Packagist 拉取此包。执行此操作的命令在 Packagist 页面上显示。请使用最新版本。
  • 查看示例用法部分，了解您打算使用的调用类型。每个示例都包含一个示例。

直接跟踪

参数

以下是所有可用参数的描述。您提供给我们的是根据您同意的合同。

必填参数

必须提供 Code 或 MemberID 参数之一

附加参数

注意以下任何属性，其值未知应从调用中省略。您提供的以下值将取决于您同意的合同。

示例购物车

以下是一个示例购物车，其中包含与 UNiDAYS 跟踪参数相关的字段：

示例用法

以下是实现您的集成的三种选项。这些示例涵盖代码化和无代码集成（请参阅实时分析 PDF 了解详细信息），并包括所有可选参数。它们旨在作为实现指南。

创建服务器 URL

此方法返回一个您可以使用它调用 API 的 URL。

所有服务器 URL 必须签名。这意味着您需要将 UNiDAYS 提供给您的签名密钥作为其中一个参数。签名密钥是 Base64 编码的 GUID。此端点接受 GET 和 POST 请求。

调用方法

获取用于进行服务器到服务器请求的 URL 的方法是 create_server_url($key)。要实现此方法，您首先需要使用 DirectTrackingDetailsBuilder 创建一个具有您要发送给我们属性的直接跟踪对象。有关此构建器的更多详细信息，请参阅此处。

一旦创建了包含您需要发送给我们详细信息的对象，请创建一个跟踪助手，将这些详细信息作为参数提供 new TrackingHelper($directTrackingDetails) 并调用 ->create_server_url($key)，其中 $key 是 UNiDAYS 提供给您的密钥。

返回

将返回一个 URL 给您，然后可以用来调用我们的 API。如果成功，将返回状态码为 204 No Content 的响应。这将适用于 POST 和 GET 请求。

示例

<?php

use Unidays;

// UNiDAYS will provide your partnerId and key
$partnerId = "somePartnerId";
$key = "someSigningKey";

$details = new DirectTrackingDetailsBuilder($partnerId, 'order123', 'GBP');
$details->withOrderTotal(209.00);
$details->withItemsUnidaysDiscount(13.00);
$details->withCode('UNI123');
$details->withItemsTax(34.50);
$details->withShippingGross(5.00);
$details->withShippingDiscount(3.00);
$details->withItemsGross(230.00);
$details->withItemsOtherDiscount(10.00);
$details->withUnidaysDiscountPercentage(10.00);
$details->withNewCustomer(true);
$directTrackingDetails = $details->build();

$helper = new TrackingHelper($directTrackingDetails);

$url = $helper->create_server_url($key);

创建脚本 URL

这也被称为我们的客户端到服务器集成。此方法返回一个可以放在您的支付后/订单成功页面中的脚本元素内的 URL 来调用 API。

未签名或已签名

为您的脚本请求创建签名URL是一个选项。为此，您需要向我们发送UNiDAYS提供的签名密钥，作为签名方法的参数之一。

$url = $helper->create_signed_script_url($key);

而不是

$url = $helper->create_script_url();

调用方法

用于向服务器发起客户端请求的URL获取方法是create_script_url()，如果您选择返回签名URL，则为create_signed_script_url($key)。要实现此方法，首先需要使用DirectTrackingDetailsBuilder创建一个直接跟踪对象，包含您想要发送给我们的属性。有关此构建器的更多详细信息，请参阅此处。

创建包含您需要发送给我们的详细信息的对象后，创建一个跟踪助手，将这些详细信息作为参数提供new TrackingHelper($directTrackingDetails)，然后调用->create_script_url()以获取未签名的URL，或者调用->create_signed_script_url($key)，其中$key是UNiDAYS提供的密钥。

返回

将返回一个URL，您可以将它放置在您的支付后/订单成功页面的脚本元素中，以调用API。如果成功，将返回状态码为200 OK的响应。这只适用于GET请求。

示例

以下示例是一个请求未签名脚本URL的示例。

<?php

use Unidays;

// UNiDAYS will provide your partnerId and key
$partnerId = "somePartnerId";

$details = new DirectTrackingDetailsBuilder($partnerId, 'order123', 'GBP');
$details->withOrderTotal(209.00);
$details->withItemsUnidaysDiscount(13.00);
$details->withCode('UNI123');
$details->withItemsTax(34.50);
$details->withShippingGross(5.00);
$details->withShippingDiscount(3.00);
$details->withItemsGross(230.00);
$details->withItemsOtherDiscount(10.00);
$details->withUnidaysDiscountPercentage(10.00);
$details->withNewCustomer(true);
$directTrackingDetails = $details->build();

$helper = new TrackingHelper($directTrackingDetails);

$url = $helper->create_script_url();

跟踪客户端

对跟踪客户端的调用类似于创建服务器URL，但不是返回URL，而是UNiDAYS发送请求并返回响应。

所有跟踪客户端调用都必须提供密钥是强制性的要求，因为UNiDAYS发送的请求都是经过签名的。

调用方法

要实现此方法，首先需要使用DirectTrackingDetailsBuilder创建一个直接跟踪对象，包含您想要发送给我们的属性。有关此构建器的更多详细信息，请参阅此处。

创建包含您需要发送给我们的详细信息的对象后，创建跟踪客户端的实例，提供这些详细信息作为参数，以及UNiDAYS提供的签名密钥new TrackingClient($directTrackingDetails, $key)，然后调用->sendRequest()。

返回

返回HttpResponseMessage。如果成功，响应应具有状态码204 No Content。

示例

以下示例设置了一些直接跟踪细节，在客户端上调用sendRequest，并将响应代码打印到控制台。

<?php

use Unidays;

// UNiDAYS will provide your partnerId and key
$partnerId = "somePartnerId";
$key = "someSigningKey";

$details = new DirectTrackingDetailsBuilder($partnerId, 'order123', 'GBP');
$details->withOrderTotal(209.00);
$details->withItemsUnidaysDiscount(13.00);
$details->withCode('UNI123');
$details->withItemsTax(34.50);
$details->withShippingGross(5.00);
$details->withShippingDiscount(3.00);
$details->withItemsGross(230.00);
$details->withItemsOtherDiscount(10.00);
$details->withUnidaysDiscountPercentage(10.00);
$details->withNewCustomer(true);
$directTrackingDetails = $details->build();

$client = new TrackingClient($directTrackingDetails, $key);

$response = $client->sendRequest();

echo $response->code;

测试端点

UNiDAYS提供了TrackingHelper对象的测试端点配置。

返回

在测试模式下配置的TrackingHelper对象将向返回给您的URL或为您发送的URL添加一个额外的参数（&Test=True）。

示例

<?php

use Unidays;

// UNiDAYS will provide your partnerId and key
$partnerId = "somePartnerId";
$key = "someSigningKey";

$details = new DirectTrackingDetailsBuilder($partnerId, 'order123', 'GBP');
$details->withOrderTotal(209.00);
$details->withItemsUnidaysDiscount(13.00);
$details->withCode('UNI123');
$details->withItemsTax(34.50);
$details->withShippingGross(5.00);
$details->withShippingDiscount(3.00);
$details->withItemsGross(230.00);
$details->withItemsOtherDiscount(10.00);
$details->withUnidaysDiscountPercentage(10.00);
$details->withNewCustomer(true);
$directTrackingDetails = $details->build();

// Pass in an aditional argument of true to instantiate the TrackingHelper object in test mode
$helper = new TrackingHelper($directTrackingDetails, true);

// The url generated will now contain the appended $Test=True parameter, this url will call our test endpoint
$url = $helper->create_server_url($key);

直接跟踪详细信息构建器

构建器的目的是在构造任何跟踪请求时使其简单直观。

构建器上的参数是强制参数

$directTrackingDetails = new DirectTrackingDetailsBuilder($partnerId, $currency, $transactionId)

然后有各种方法可用于构建您想要发送给我们的信息，可以按示例进行链式调用。这些与文档顶部的参数相匹配。

  • withMemberId(base64 encoded guid)
  • withCode(string)
  • withOrderTotal(decimal)
  • withItemsUnidaysDiscount(decimal)
  • withItemsTax(decimal)
  • withShippingGross(decimal)
  • withShippingDiscount(decimal)
  • withItemsGross(decimal)
  • withItemsOtherDiscount(decimal)
  • withUnidaysDiscountPercentage(decimal)
  • withNewCustomer(bool)

仅连接您已合同约定的值。使用每个方法不是必需的。

要连接的最后一个调用是 ->build()，它创建对象。

示例

<?php

use Unidays;

$details = new DirectTrackingDetailsBuilder('somePartnerId', 'order123', 'GBP');
$details->withOrderTotal(209.00);
$details->withItemsUnidaysDiscount(13.00);
$details->withCode('UNI123');
$details->withItemsTax(34.50);
$details->withShippingGross(5.00);
$details->withShippingDiscount(3.00);
$details->withItemsGross(230.00);
$details->withItemsOtherDiscount(10.00);
$details->withUnidaysDiscountPercentage(10.00);
$details->withNewCustomer(true);
$directTrackingDetails = $details->build();

无代码验证

如果您已同意向 UNiDAYS 成员提供无代码体验，并直接跟踪，您还需要实现 '无代码 API'，这将帮助您解析和验证我们直接发送到您网站的已签名流量。

无代码 API

调用方法

首先使用由 UNiDAYS 提供的密钥调用 CodelessUrlVerifier new CodelessUrlVerifier($key)。然后使用 ud_s、ud_t 和 ud_h 的值作为参数调用 verify_url_params($ud_s, $ud_t, $ud_h) 方法。

返回

如果该方法成功验证了传入请求的哈希值，将返回请求的 DateTime；否则返回 null。

示例

<?php

use Unidays;

// Your key as provided by UNiDAYS
$key = "someSigningKey";

// Obtain parameters from the query string. Be sure to URL Decode them
$ud_s = "Do/faqh330SGgCnn4t3X4g==";
$ud_t = "1395741712";
$ud_h = "i38dJdX+XLKuE4F5tv+Knpl5NPtu5zrdsjnqBQliJEJE4NkMmfurVnUaT46WluRYoD1/f5spAqU36YgeTMCNeg==";

$verifier = new CodelessUrlVerifier($key);
$verifiedAt = $verifier->verify_url_params($ud_s, $ud_t, $ud_h);

贡献

此项目被设置为开源项目。因此，如果您有任何关于功能、改进代码本身或遇到任何问题的建议；您可以将它们提出并/或建议更改实现。

如果您有兴趣为此代码库做出贡献，请遵循 贡献指南。这包含有关直接贡献和提出功能请求或错误报告的指南。在进行上述任何操作时，请遵守我们的 行为准则。