README

README

提供了一个与Virgin Money Giving API交互的PHP库。

此库将帮助从API推送和拉取数据。不幸的是，API有很多未记录的怪癖，这个库希望阻止开发者陷入其中。

先决条件

API密钥

要与VGM API交互，您需要获取API密钥。为此，您需要在网站上注册（https://developer.virginmoneygiving.com/member/register）。

您需要在此处的应用程序概览页面创建一个应用程序：/apps/myapps。

然后，在密钥概览页面，您可以获取您的API密钥：/apps/mykeys。

由于某种原因，您需要为不同的API调用获取不同的API密钥。列表可以在以下位置找到

https://developer.virginmoneygiving.com/our_apis

测试数据

在测试沙盒时，已经设置了一些测试数据

慈善机构

筹款者

@todo - 如果有

活动

@todo - 捕获一些默认的

安装

使用以下命令安装最新版本

$ composer require reason-digital/virgin-money-giving-api

使用方法

筹款者搜索

要使用筹款者搜索，您需要使用您的筹款者开发者API密钥。任何其他密钥将返回403响应。

<?php
// Initialise the connector
$fundraiserConnector = new FundraiserVmgConnector('API_KEY', $guzzleClient, $testMode = false);

try {
    $response = $fundraiserConnector->search('Test', 'User');
} catch (ConnectorException $exception) {
    // VMG error message No fundraiser found for  forename=User surname=Test
    $exception->getErrorMessage();
    // VMG erorr code 001.02.011
    $exception->getErrorCode();
}

$response 是 Responses/FundraiserSearchResponse.php 类的实例。它有一个 hasMatches(): bool 方法。

创建筹款者账户

要创建筹款者账户，您需要使用您的筹款者开发者API密钥。任何其他密钥将返回403响应。

此API调用有几个需要注意的问题。首先，您传递给 createFundraiserAccount 的 callback url 需要与您在VMG账户中设置的相匹配，否则您将不会在响应中收到访问代码。相反，您将收到以下响应

OAuth访问令牌未创建。错误代码：<-2001> 消息：<Invalid redirect_uri> 描述：<N/A>

如果 callback url 匹配，则您将收到以下响应

令牌有效期1500秒

此访问代码有效期为1500秒，允许您代表筹款者创建筹款页面。

一些字段需要进行验证。它们可以在以下位置找到：Models/FundraiserTest.php

<?php
// Initialise the connector
$fundraiserConnector = new FundraiserVmgConnector('API_KEY', $guzzleClient, $testMode = false);

try {
    $fundraiser = new Fundraiser();
    $fundraiser->setTitle('Mr')
        ->setForename('firstName')
        ->setSurname('lastName')
        ->setAddressLine1('streetName')
        ->setAddressLine2('streetAddress')
        ->setTownCity('city')
        ->setCountyState('county')
        ->setPostcode('postcode')
        ->setCountryCode('countryCode')
        ->setPreferredTelephone('12345678912')
        ->setEmailAddress('Email')
        ->setPersonalUrl('url')
        ->setTermsAndConditionsAccepted('Y')
        ->setDateOfBirth('20010101');
    
    $fundraiserResponse = $fundraiserConnector->createFundraiserAccount($fundraiser, 'CALLBACK_URL');
} catch (ConnectorException $exception) {
    $exception->getErrorMessage();
    $exception->getErrorCode();
}

$fundraiserResponse 是 Responses/FundraiserCreateResponse.php 类的实例。

这包含了 Fundraiser 和返回的访问代码。

创建带有令牌的筹款者页面

注意：首先，您需要访问令牌才能代表用户创建页面。这仅在您已按上述方式以编程方式创建用户的账户时才可用。

如果没有这个，以下将不起作用。

首先，我们假设您有以下内容

• $fundraiser 是 Models/Fundraiser.php 对象，如上所述
• $fundraiserResponse 是 Responses/FundraiserCreateResponse.php 对象，如上所述

然后

<?php
// Initialise the connector
$fundraiserConnector = new FundraiserVmgConnector('API_KEY', $guzzleClient, $testMode = false);

try {
    $page = new Page();
    $page->setPageTitle()
        ->setEventResourceId('EVENT_ID')
        ->setFundraisingTarget(2000.00)
        ->setCharityResourceId('CHARITY_ID')
        ->setCharitySplits([
            [
                'charityResourceId' => '6a5880c9-13e4-4cf4-987e-931f3899b9d5',
                'charitySplitPercent' => 50
            ],
            [
                'charityResourceId' => '8da32779-1c1b-4d20-8714-df3219836618',
                'charitySplitPercent' => 50
            ]
        ]);
    
    // Now create the page.
    $pageCreateResponse = $fundraiserConnector->createFundraiserPage($page, $fundraiser, $fundraiserResponse->getAccessToken());
} catch (ConnectorException $exception) {
    $exception->getErrorMessage();
    $exception->getErrorCode();
}

$pageCreateResponse 是 Responses/PageCreateResponse.php 类的实例。

这包含了 Page 和页面URI，可以通过 $pageCreateResponse->getPageURI(); 访问。

运行测试

Travis CI 已经配置好用于在PR和master分支上运行测试。要本地运行测试，您需要通过以下命令拉取带有开发依赖的代码仓库：

composer self-update composer install --prefer-source --no-interaction --dev

安装完成后，运行 phpunit 将会运行测试。

路线图

• 为活动获取筹款页面 - #5
• 获取活动的筹款总额
• 为已经拥有账户的人创建筹款页面
  • 处理认证令牌
  • 创建账户（是否与相同的API调用相同？）