README

目录

• 目标
• 安装
• 使用
• 开发
• 测试
• 约定

目标

Dues旨在提供一个高级API用于处理支付，特别是订阅。

它设计为与处理器无关，但目前仅支持Braintree。

安装

目前Dues尚未发布到packagist。在它发布之前，建议使用composer的vcs功能从main分支安装dues。

您的composer.json应包含以下内容

{
  "repositories": [
    {
      "url": "https://github.com/teamgantt/dues",
      "type": "vcs"
    }
  ],
  "require": {
    "teamgantt/dues": "dev-main",
  }
}

请参阅composer文档以指定特定的提交。

使用

Dues的高级API通过使用网关实现构造Dues实例来访问。

use TeamGantt\Dues\Dues;
use TeamGantt\Dues\Processor\Braintree;

$gateway = new Braintree([
    'environment' => $_ENV['BRAINTREE_ENVIRONMENT'],
    'merchantId' => $_ENV['BRAINTREE_MERCHANT_ID'],
    'publicKey' => $_ENV['BRAINTREE_PUBLIC_KEY'],
    'privateKey' => $_ENV['BRAINTREE_PRIVATE_KEY'],
]);

$dues = new Dues($gateway);

Dues支持的所有功能都可以在Dues类中找到。[链接](https://github.com/teamgantt/dues/blob/HEAD/src/Dues.php)

注意：Dues的一些公共API通过特性混合。

事件

Dues通过addListener方法提供了对处理某些事件的支持。此方法期望实现EventListener接口。

interface EventListener
{
    public function onAfterCreateCustomer(Customer $customer): void;

    public function onAfterUpdateCustomer(Customer $customer): void;

    public function onBeforeCreateCustomer(Customer $customer): void;

    public function onBeforeUpdateCustomer(Customer $customer): void;

    public function onAfterCreateSubscription(Subscription $subscription): void;

    public function onAfterUpdateSubscription(Subscription $subscription): void;

    public function onBeforeCreateSubscription(Subscription $subscription): void;

    public function onBeforeUpdateSubscription(Subscription $subscription): void;
}

可以通过调用带有相同实例的removeEventListener来删除侦听器。

$dues->removeListener($listener);

事件对于日志记录、分析和其他集成（如处理税收）非常有用。

开发

Dues针对PHP版本8.1进行开发

提供了一个Dockerfile，用于一致的开发环境。

bin/中的命令假定有一个名为dues且标签为dev的docker镜像。您可以从存储库的根目录构建此镜像

docker build . -t dues:dev

虽然不是必需的，但建议在开发中使用direnv。如果已安装direnv，则在进入项目目录时将自动加载.envrc文件。这将允许开发者使用php和composer命令而无需在本地安装它们。所有composer命令都将通过docker容器透明地运行。

在没有direnv的情况下从docker容器执行

您可以直接使用bin/中提供的脚本

$ bin/composer test

测试

Dues旨在达到非常高的测试覆盖率。测试使用PHPUnit编写。

测试套件分为单元测试和集成测试。

在本地运行集成测试时可能会有所不同，但套件设计为在CI环境中运行。CI测试针对由TeamGantt配置的BrainTree沙盒环境运行。

要本地运行单元测试，请运行composer test:unit。

要本地运行集成测试，请运行composer test:integration。

集成测试和单元测试没有通过任何类型的文件命名约定来分离，而是分组在一起。集成测试应使用@group注释进行标记。

/**
 * @group integration
 */
public function testAProcesserRequest()
{

}

测试在tests/Feature目录中按功能组织。

BrainTree测试

为确保测试环境的一致性，Braintree的测试是在沙盒环境中运行的。关闭“重复交易检查”功能非常重要。这将允许集成运行多次使用相同数据的测试，而不会出现意外结果。

请参阅Braintree的文档以获取有关配置重复交易检查的更多信息。

约定

Dues旨在保持风格和类型正确性的一致性。使用PHP_CodeSniffer强制执行代码规范。规范列表可以在.php-cs-fixer.php文件中找到。

使用phpstan进行静态分析。有关配置信息，请参阅phpstan.neon。

提供了一些composer脚本来检查规范和运行静态分析。

$ composer run fix
$ composer run check
$ composer run analyse

注意： composer run fix将自动修复任何可以自动修复的CodeSniffer问题。这并不总是可能的，因此建议在提交代码之前运行composer run check。