README

此软件包为将Rave支付网关集成到您的PHP应用程序提供了一个非常简单的接口。它是Femi Olanipekun最初开发的Flutterwave-Rave-PHP-SDK软件包的扩展。

1. 入门
   • 安装
   • 配置
   • 设置支付
2. 高级用法
   • 自定义支付字段
   • 支付元数据
   • 事件处理器
3. 许可证

入门

安装

您可以使用Composer将此软件包作为项目依赖项安装。

composer require gladcodes/ravephp

这将把RavePHP软件包添加到项目根目录的vendor文件夹中。然后，您可以通过以下方式使用自动加载器在我们的PHP脚本中引用此软件包：

<?php

/**
 * REQUIRE AUTOLOADER
 *
 * Ensure that the require path resolves correctly to:
 * {PROJECT_ROOT_DIR}/vendor/autoload.php
 *
 * [Hint]
 * You could choose to define a constant for {PROJECT_ROOT_DIR}
 * And then make it available to all your PHP scripts.
 */

require_once dirname(__DIR__).'/vendor/autoload.php';

配置

安装后，您可以设置PHP应用程序的配置变量。此软件包要求在项目的根目录中存在一个包含所有配置变量的.env文件。以下配置变量对于Rave集成是必需的。

在项目根目录中创建一个新的.env文件（如果已存在，请编辑文件），内容如下。请确保用您自己的配置值替换它们。

# RAVE CONFIG VARIABLES (BEGIN)

RAVE_APP_NAME='YOUR_APP_NAME'

RAVE_STAGING_PUBLIC_KEY='FLWPUBK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-X'
RAVE_STAGING_SECRET_KEY='FLWSECK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-X'

RAVE_LIVE_PUBLIC_KEY='FLWPUBK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-X'
RAVE_LIVE_SECRET_KEY='FLWSECK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-X'

# RAVE CONFIG VARIABLES (END)

版本控制和.env文件
建议您从版本控制中删除.env文件，因为它通常包含一些敏感信息，如API密钥，这些信息不应该对外界可见。如果您使用Git进行版本控制，请记住将.env条目添加到项目的.gitignore文件中。

设置支付

支付表单

要进行支付，您需要设置一个支付表单和一个PHP 支付脚本。当提交时，支付表单应向支付脚本发送一个表单编码的POST请求。换句话说，支付表单的action属性应该是支付脚本。请查看支付表单示例以获取示例支付表单片段。默认情况下，支付表单应包含以下字段。

支付脚本

支付脚本是在此处初始化和运行Rave以处理从支付表单发送的支付请求的地方。Rave从PHP的$_POST超全局变量中获取支付请求的有效负载。以下是基本支付脚本的片段。该片段假设支付脚本位于项目的根目录中。

// Assuming you are in the project root directory
require_once __DIR__.'/vendor/autoload.php';

// Use the Rave class provided by the Rave namespace
use Rave\Rave;

/**
 * RAVE CONFIG
 *
 * env (string)
 * The Rave environment.
 * Default 'staging'
 *
 * autoRefs (bool)
 * Automatically generate transaction reference.
 * Default: true
 */

$config = [
  'env' => 'staging',
  'autoRefs' => false
];

/**
 * RAVE INITIALIZATION
 *
 * The Rave::init() method takes an optional $config array
 * And returns a Rave instance
 *
 * Rave cannot be instantiated using the `new` keyword.
 */

$rave = Rave::init($config)->run();

高级用法

自定义支付字段

您可以将Rave设置为查找支付表单中除默认名称以外的自定义支付字段名称。例如，假设您的支付表单使用一个payment_amount字段来表示交易支付金额，以及一个payment_currency字段来表示货币。您可以使用Rave实例的fields()方法将自定义字段映射到默认字段。

$fieldMappings = [
  'amount' => 'payment_amount',
  'currency' => 'payment_currency'
];

$rave = Rave::init()->fields($fieldMappings);

$rave->run();

注意：自定义字段名称只能包含字母数字字符（0-9A-Za-z）和下划线（_）。此外，字段名称不能以数字开头。因此，'2nd_address'和'address-2'是无效的，但'address_2'是有效的。

您的支付表单应反映自定义字段

<input type="hidden" name="payment_amount" value="100">

<input type="hidden" name="payment_currency" value="USD">

支付元数据

有时你可能想在付款请求中发送一些元数据来进一步描述付款。您可以将Rave设置为在您的付款表单中查找元数据字段名称。例如，假设您想在付款数据中发送customer_ip_address和customer_user_agent。您可以使用Rave实例的meta()方法指定元数据字段。

$metaFields = [ 'customer_ip_address', 'customer_user_agent' ];

$rave = Rave::init()->meta($metaFields);

$rave->run();

注意：元数据字段名称必须只包含字母数字字符（0-9A-Za-z）和下划线（_）。此外，字段名称不能以数字开头。因此，'2nd_address'和'address-2'是无效的，但'address_2'是有效的。

您的付款表单应包括元数据字段

<input type="hidden" name="customer_ip_address" value="127.0.0.1">

<input type="hidden" name="customer_user_agent" value="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36">

事件处理器

Rave\Event\BaseEventHandler的一个实例用作Rave实例的默认事件处理器。该事件处理器仅将文本输出到输出端，对每个事件进行响应。您可以定义自己的自定义事件处理器，以替换默认处理器。以下是一些实现自己的事件处理器的指南。

1. 必须实现Rave\Event\EventHandlerInterface
   您的事件处理器必须实现Rave\Event\EventHandlerInterface的以下方法

1. 使用listener()方法将事件处理器的实例附加到Rave实例
   创建您自定义事件处理器的新的实例，并使用Rave实例的listener()方法将其附加到Rave实例。

use Rave\Rave;
use Rave\Event\EventHandlerInterface;

class MyEventHandler implements EventHandlerInterface
{
   /**
    * This is called when a transaction is initialized
    * @param object $initializationData (This is the initial transaction data as passed)
    **/
   public function onInit($initializationData) {}

   /**
    * This is called only when a transaction is successful
    * @param object $transactionData (This is the transaction data as returned from the Rave payment gateway)
    **/
   public function onSuccessful($transactionData) {}

   /**
    * This is called only when a transaction failed
    * @param object $transactionData (This is the transaction data as returned from the Rave payment gateway)
    **/
   public function onFailure($transactionData) {}

   /**
    * This is called when a transaction is requeried from the payment gateway
    * @param string $transactionReference (This is the transaction reference as returned from the Rave payment gateway)
    **/
   public function onRequery($transactionReference) {}

   /**
    * This is called when a transaction requery returns with an error
    * @param string $requeryResponse (This is the error response gotten from the Rave payment gateway requery call)
    **/
   public function onRequeryError($requeryResponse) {}

   /**
    * This is called when a transaction is cancelled by the user
    * @param string $transactionReference (This is the transaction reference as returned from the Rave payment gateway)
    **/
   public function onCancel($transactionReference);

   /**
    * This is called when a transaction doesn't return with a success or a failure response.
    * @param string $transactionReference (This is the transaction reference as returned from the Rave payment gateway)
    * @param object $data (This is the data returned from the requery call)
    **/
   public function onTimeout($transactionReference,$data);
}

$eventHandler = new MyEventHandler;

$rave = Rave::init()->listener($eventHandler);

$rave->run();

许可证

本软件包受MIT许可证的保护。以下是许可证副本（请仔细阅读）。

MIT License

Copyright (c) 2018 Glad Chinda

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.