README

MangopaySDK 是一个 PHP 客户端库，用于与 Mangopay REST API 交互。

兼容性说明

• 自 SDK 的 v2.1 版本起，您必须使用 API 的至少 v2.01 版本（有关所需更改的更多信息，请参阅 此处）
• 如果在 SDK 更新（尤其是更新到 SDK 的 v2.0 版本）后遇到身份验证和/或临时令牌文件问题，您可能需要只需删除您的临时文件（您通过 $api->Config->TemporaryFolder 指定）- 这允许它在下次需要时正确再生

要求

要使用此 SDK，您将需要（至少）

• PHP 5.6 或更高版本
• cURL（包括在标准 PHP 发行版中启用）
• OpenSSL（包括在标准 PHP 发行版中启用）
• psr/log v1.0
• 您不需要使用 Composer，但强烈建议您这样做（特别是对于处理 PSR Log 库的依赖项）

使用 Composer 安装

您可以使用 Composer 将 Mangopay SDK 库作为项目中的依赖项（这是首选技术）。如果您尚未安装 Composer，请按照 这些安装说明 进行操作。仓库中包含 composer.json 文件，并且它已从 Packagist 引用。

使用 Composer 进行安装既简单又可靠

步骤 1 - 通过执行以下命令将 Mangopay SDK 添加为依赖项

you@yourhost:/path/to/your-project$ composer require mangopay/php-sdk-v2

步骤 2 - 使用 Composer 更新您的依赖项

you@yourhost:/path/to/your-project$ composer update

步骤 3 - 最后，务必在您的项目中包含自动加载器

require_once '/path/to/your-project/vendor/autoload.php';

库已添加到您的依赖项中，并准备好使用。

不使用 Composer 的安装

该项目试图遵守 PSR-4 规范，以便从文件路径自动加载类。命名空间前缀为 MangoPay\，基本目录为 /path/to/your-project/。

如果您不使用 PSR-4 或 Composer，则安装与下载库并将其存储在项目可包含的任何位置一样简单（但请记住包含所需的库依赖项）

    require_once '/path/to/your-project/MangoPay/Autoloader.php';

或者，您可以从 发布页面（查找 mangopay2-php-sdk-[RELEASE_NAME].zip 文件）下载整个包（即包含所有必需依赖项的包）。解压缩您下载的 zip 文件，并在项目中包含自动加载器

    require_once '/path/to/your-project/mangopay2-php-sdk/vendor/autoload.php';

许可

MangopaySDK 在 MIT 许可证下分发，请参阅 LICENSE 文件。

单元测试

测试放在 /path/to/your-project/tests/ 下。/tests/suites/all.php 套件运行所有测试。您也可以使用 /tests/cases/*.php 中的任何测试用例来运行单个测试用例。

联系方式

使用GitHub上的问题跟踪器报告错误或建议功能。

账户创建

您可以通过在Mangopay网站上注册来获取一个免费的沙箱账户或申请一个生产账户（请注意，验证您的生产账户涉及多个步骤，因此请提前考虑，以便在实际上线之前完成）。

配置

使用上述注册过程提供的凭证信息，您应将$api->Config->ClientId设置为您的Mangopay ClientId，并将$api->Config->ClientPassword设置为您的Mangopay APIKey。

您还需要在$api->Config->TemporaryFolder中设置一个文件夹路径，该SDK需要存储临时文件。此路径应位于您的www文件夹之外。可以是/tmp/、/var/tmp/或任何PHP可以写入的其他位置。您必须为沙箱和生产环境使用不同的文件夹。

$api->Config->BaseUrl默认设置为沙箱环境。要启用生产环境，请将其设置为https://api.mangopay.com。

require_once '/path/to/your-project/vendor/autoload.php';
$api = new MangoPay\MangoPayApi();

// configuration
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-client-password';
$api->Config->TemporaryFolder = '/some/path/';
//$api->Config->BaseUrl = 'https://api.mangopay.com';//uncomment this to use the production environment

//uncomment any of the following to use a custom value (these are all entirely optional)
//$api->Config->CurlResponseTimeout = 20;//The cURL response timeout in seconds (its 30 by default)
//$api->Config->CurlConnectionTimeout = 60;//The cURL connection timeout in seconds (its 80 by default)
//$api->Config->CertificatesFilePath = ''; //Absolute path to file holding one or more certificates to verify the peer with (if empty, there won't be any verification of the peer's certificate)

// call some API methods...
try {
    $users = $api->Users->GetAll();
} catch(MangoPay\Libraries\ResponseException $e) {
    // handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()
} catch(MangoPay\Libraries\Exception $e) {
    // handle/log the exception $e->GetMessage()
}

示例用法

require_once '/path/to/your-project/vendor/autoload.php';
$api = new MangoPay\MangoPayApi();

// configuration
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-client-password';
$api->Config->TemporaryFolder = '/some/path/';

// get some user by id
try {
    $john = $api->Users->Get($someId);
} catch(MangoPay\Libraries\ResponseException $e) {
    // handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()
} catch(MangoPay\Libraries\Exception $e) {
    // handle/log the exception $e->GetMessage()
}

// change and update some of his data
$john->LastName .= " - CHANGED";
try {
    $api->Users->Update($john);
} catch(MangoPay\Libraries\ResponseException $e) {
    // handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()
} catch(MangoPay\Libraries\Exception $e) {
    // handle/log the exception $e->GetMessage()
}

// get all users (with pagination)
$pagination = new MangoPay\Pagination(1, 8); // get 1st page, 8 items per page
try {
    $users = $api->Users->GetAll($pagination);
} catch(MangoPay\Libraries\ResponseException $e) {
    // handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()
} catch(MangoPay\Libraries\Exception $e) {
    // handle/log the exception $e->GetMessage()
}

// get his bank accounts
$pagination = new MangoPay\Pagination(2, 10); // get 2nd page, 10 items per page
try {
    $accounts = $api->Users->GetBankAccounts($john->Id, $pagination);
} catch(MangoPay\Libraries\ResponseException $e) {
    // handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()
} catch(MangoPay\Libraries\Exception $e) {
    // handle/log the exception $e->GetMessage()
}

在Symfony项目中使用Composer的示例用法

您可以在Symfony项目中将Mangopay功能集成到Service中。

MangoPayService.php

<?php

namespace Path\To\Service;

use MangoPay;


class MangoPayService
{

    private $mangoPayApi;

    public function __construct()
    {
        $this->mangoPayApi = new MangoPay\MangoPayApi();
        $this->mangoPayApi->Config->ClientId = 'your-client-id';
        $this->mangoPayApi->Config->ClientPassword = 'your-client-password';
        $this->mangoPayApi->Config->TemporaryFolder = '/some/path/';
        //$this->mangoPayApi->Config->BaseUrl = 'https://api.sandbox.mangopay.com';
    }

    /**
     * Create Mangopay User
     * @return MangopPayUser $mangoUser
     */
    public function getMangoUser()
    {

        $mangoUser = new \MangoPay\UserNatural();
        $mangoUser->PersonType = "NATURAL";
        $mangoUser->FirstName = 'John';
        $mangoUser->LastName = 'Doe';
        $mangoUser->Birthday = 1409735187;
        $mangoUser->Nationality = "FR";
        $mangoUser->CountryOfResidence = "FR";
        $mangoUser->Email = 'john.doe@mail.com';

        //Send the request
        $mangoUser = $this->mangoPayApi->Users->Create($mangoUser);

        return $mangoUser;
    }
}

日志记录

Mangopay使用PSR3 LoggerInterface。您可以向API提供自己的记录器。以下是一个展示Monolog集成的示例

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

...

$logger = new Logger('sample-logger');
$logger->pushHandler(new StreamHandler($logConfig['path'], Logger::DEBUG));

$this->mangoPayApi = new MangoPay\MangoPayApi();
$this->mangoPayApi->setLogger($logger);

验证速率限制状态

根据API文档（https://docs.mangopay.com/guide/rate-limiting），Mangopay提供了一种验证API调用次数、剩余次数以及计数器何时重置的方法。因此，有4组速率限制可用

1. 过去15分钟
2. 过去30分钟
3. 过去60分钟
4. 过去24小时

此信息可从MangoPayApi实例中获取，如下例所示

<?php

namespace Path\To\Service;

use MangoPay;


class MangoPayService
{

    /**
    * @var MangoPay\MangoPayApi
    */
    private $mangoPayApi;

    public function __construct()
    {
        $this->mangoPayApi = new MangoPay\MangoPayApi();
        $this->mangoPayApi->Config->ClientId = 'your-client-id';
        $this->mangoPayApi->Config->ClientPassword = 'your-client-password';
        $this->mangoPayApi->Config->TemporaryFolder = '/some/path/';
        //$this->mangoPayApi->Config->BaseUrl = 'https://api.sandbox.mangopay.com';
    }

    public function verifyRateLimits()
    {
        // This is an array of 4 RateLimit objects.
        $rateLimits = $this->mangoPayApi->RateLimits;
        print "\nThere were " . $rateLimits[0]->CallsMade . " calls made in the last 15 minutes";
        print "\nYou can do " . $rateLimits[0]->CallsRemaining . " more calls in the next 15 minutes";
        print "\nThe 60 minutes counter will reset at " . date("Y-m-d\TH:i:s\Z", $rateLimits[0]->ResetTimeTimestamp);
        print "\nThere were " . $rateLimits[2]->CallsMade . " calls made in the last 60 minutes";
        print "\nYou can do " . $rateLimits[2]->CallsRemaining . " more calls in the next 60 minutes";
        print "\nThe 60 minutes counter will reset at " . date("Y-m-d\TH:i:s\Z", $rateLimits[2]->ResetTimeTimestamp);
    }
}