README

用于使用 HelloAsso.com 提供的工具的库

V3 : 处理 API v3
V5 : 处理 API v5

先决条件

PHP 5.6
Web服务器（Apache、...）
HelloAsso.com 账户
HelloAsso API 访问权限（密钥 + 密码）

安装

简单地将包含 HelloAsso 代码的文件夹复制到您的磁盘上（或克隆存储库）

处理 API v5

推荐版本。

初始化

使用 HelloAsso 类初始化库，并提供其 client_id 和 client_secret，然后调用 authenticate() 来启动身份验证请求

require_once 'HelloAsso.php'; // Facultatif si autoload.php est chargé

\HelloAsso\V5\HelloAsso::initialize()
    ->setClient('my_client_id', 'my_secreat_id')
    ->setOrganization('organization-slug')
    ->authenticate()
;

请求

ResourceQuery 允许对资源进行查询。

资源列表：查询

获取支付列表的示例

use \HelloAsso\V5\Resource\Query\Payment as PaymentQuery;
use \HelloAsso\V5\Api\Pagination;

$pagination = null; /* @var Pagination $pagination */
$payment_list = PaymentQuery::create()
    ->setFromDate(date('Y').'-01-01') // Depuis le premier janvier
    ->setToDate(date('Y-m-d')) // Jusqu'à aujourd'hui
    ->search() // Appel de la requête "search"
    ->getCollection($pagination) // Récupère la collection de Payment
    ;
    
echo 'Current page : ' . $pagination->page . PHP_EOL;
echo 'Max page : ' . $pagination->max_page . PHP_EOL;
echo 'Page size : ' . $pagination->result_per_page . PHP_EOL;

// --------------------
// Ou bien, en récupérant d'abord la réponse
// --------------------

$response = PaymentQuery::create()
    ->setFromDate(date('Y').'-01-01') // Depuis le premier janvier
    ->setToDate(date('Y-m-d')) // Jusqu'à aujourd'hui
    ->search() // Appel de la requête "search"
    ;

$payment_list = $response->getCollection();
    
echo 'Current page : ' . $response->getPagination()->page . PHP_EOL;
echo 'Max page : ' . $response->getPagination()->max_page . PHP_EOL;
echo 'Page size : ' . $response->getPagination()->result_per_page . PHP_EOL;

单个记录：get()

要获取单个记录，请使用 get() 方法。

use \HelloAsso\V5\Resource\Query\Payment as PaymentQuery;
use \HelloAsso\V5\Resource\Payment;

$payment_id = 3;
$payment = PaymentQuery::create()->get($payment_id)->getResource();

// -------------------------
// Ou bien sous forme statique :
// -------------------------

$payment_id = 3;
$payment = Payment::get($payment_id);

所有记录：getAll()

use \HelloAsso\V5\Resource\Payment;
use \HelloAsso\V5\Api\Pagination;

$pagination = null; /* @var Pagination $pagination */
$payment_list = Payment::getAll($pagination);

echo 'Current page : ' . $pagination->page . PHP_EOL;
echo 'Max page : ' . $pagination->max_page . PHP_EOL;
echo 'Page size : ' . $pagination->result_per_page . PHP_EOL;

刷新资源

当资源可能不完整时，例如它来自列表、另一个资源或 callback，可能需要执行 get() 类型的请求来刷新其数据

use \HelloAsso\V5\Resource\Payment;

// Récupérer toutes les infos d'un ORDER depuis un PAYMENT

$payment_order = Payment::get(3)->order->refresh();

// Depuis un Callback

$callback = new \HelloAsso\V5\Callback();
if ($callback->isPayment())
{
    $payment = $callback->getPayment()->refresh();
}

在这些情况下不要执行 refresh()，会导致只有部分数据。

回调

当 HelloAsso 向指定的回调 URL 发送通知时，支付/表单/订单的数据将作为 POST 请求的正文传输。

Callback 类允许处理这些数据以获取资源

use HelloAsso\V5\Callback;

$callback = new Callback(); // Suffisant pour initialiser depuis le POST body

if ($callback->isPayment())
{
    $payment = $callback->getPayment(); // Données transmises (partielles)
    $payment->refresh(); // Requête cURL pour récupéer toute la ressource
}

if ($callback->isForm())
{
    $form = $callback->getForm(); // Données transmises (partielles)
    $payment->refresh(); // Requête cURL pour récupéer toute la ressource
}

if ($callback->isOrder())
{
    $order = $callback->getOrder(); // Données transmises (partielles)
    $order->refresh(); // Requête cURL pour récupéer toute la ressource
}

资源

模拟 API 返回数据的对象

\HelloAsso\V5\Resource\Payment - 一笔支付
\HelloAsso\V5\Resource\Organization - 结构信息
\HelloAsso\V5\Resource\Item - 销售项目
\HelloAsso\V5\Resource\Form - 活动（销售、会员、...）
\HelloAsso\V5\Resource\Order - 订单

资源的结构化数据

\HelloAsso\V5\Data\Payer - 付款人信息
\HelloAsso\V5\Data\CustomField - 自定义字段
\HelloAsso\V5\Data\CustomData - 抽象 - 自定义字段列表
\HelloAsso\V5\Data\User - 用户信息
\HelloAsso\V5\Data\Meta - 创建/修改日期信息
\HelloAsso\V5\Data\Banner - 活动横幅
\HelloAsso\V5\Data\Amount - 金额信息：总额、增值税、折扣

资源请求

\HelloAsso\V5\Query\Form
\HelloAsso\V5\Query\Item
\HelloAsso\V5\Query\Order
\HelloAsso\V5\Query\Payment
\HelloAsso\V5\Query\PaymentRefund - 扩展 Payment 以调用 refund() 方法

API 响应

这是 Api\Response 对象。

方法

setResourceClass(string) : Api\Response : 允许定义 getResource() 和 getCollection() 默认使用的类。用于 ResourceQuery 的通用用途。
getHttpCode() : int : 返回 HTTP 状态码
isCollection() : boolean : 如果响应是资源集合
isError() : boolean : 如果响应是错误
throwException() : Api\Response : 抛出可能存在的异常。
getException() : Api\ResponseError : 返回可能存在的异常
getData() : stdClass : 解码的 JSON 数据
getPagination() : Api\Pagination : API 返回的分页
getResource(string) : Resource : 返回资源
getCollection(&Pagination) : Resource[] : 返回资源列表

查看 Query 和 Response 的使用示例

API v3 操作

此API已过时

HelloAsso.php 是 HelloAsso API 的入口和配置点
Callback.php 及其派生类（callback/ 目录）用于处理通知
Resource.php 及其派生类（resource/ 目录）用于处理资源（对象）

使用方法

简单包含 HelloAsso.php 并使用密钥配置 API。

require_once 'HelloAsso.php';

HelloAsso\HelloAsso::apiConfig("id-api-helloasso", "password-api-helloasso");

部分使用

您可以使用 HelloAsso API / 资源部分，并使用较少的文件。

然后仅包含 Resource.php，并删除 callback/ 目录和 Callback.php、HelloAsso.php 文件。

配置是通过定义静态变量完成的 \HelloAsso\Api\Query::setDefaultAuth($api_id, $api_pass);

require_once 'Resource.php';

use HelloAsso\Api\Query;

Query::setDefaultAuth("id-api-helloasso", "password-api-helloasso");

对象列表

回调

这些对象表示在接收 HelloAsso 通知时传递的数据

\HelloAsso\V3\Callback\Campaign : 营销活动创建/编辑通知
\HelloAsso\V3\Callback\Payment : 付款通知

方法

\HelloAsso\V3\Callback\Campaign::getCampaign() : \HelloAsso\V3\Resource\Campaign
\HelloAsso\V3\Callback\Payment::getPayment() : \HelloAsso\V3\Resource\Payment
\HelloAsso\V3\Callback\Payment::getAction() : \HelloAsso\V3\Resource\Action

资源

模拟 API 返回数据的对象

\HelloAsso\V3\Resource\BasicCampaign : 基本活动（公开信息）
\HelloAsso\V3\Resource\Action
\HelloAsso\V3\Resource\Campaign
\HelloAsso\V3\Resource\Payment
\HelloAsso\V3\Resource\Organism

方法

API getter 方法

每个资源（除 BasicCampaign 外）都具有以下静态方法

get(string ID) : Resource
getAll(& Pagination) : Resource[]

BasicCampaign 拥有静态搜索方法

searchForOrganismSlug(string $slug, string $type = NULL, int $page = NULL, int $results_per_page = NULL, Pagination & $pagination = NULL) : BasicCampaign[]

用于根据 slug 搜索给定组织的活动

searchForOrganismId(string $id, string $type = NULL, int $page = NULL, int $results_per_page = NULL, Pagination & $pagination = NULL) : BasicCampaign[]

用于根据 id 搜索给定组织的活动

其他方法

一个操作与一个付款、一个活动和一个人相关联。因此，有相应的 getter 方法

\HelloAsso\V3\Resource\Action::getCampaign() : Campaign
\HelloAsso\V3\Resource\Action::getOrganism() : Organism
\HelloAsso\V3\Resource\Action::getPayment() : Payment

请求和响应

自定义请求

要创建和执行自定义 API 请求，请使用 \HelloAsso\Api\Query 类

构造函数的参数是

string ressource : 要查找的资源，或资源类的完整名称（使用 ::class）
string id (可选) : 要获取的资源 ID

方法

静态方法 Query::create(string ressource[, string id]) 用于获取新请求
setId(string) 用于要获取的资源的 ID
setPage(int) 要获取的页码
setResultsPerPage(int) 每页的结果数量
setCampaignId(string) 限制搜索的活动的 ID
setOrganismId(string) 限制搜索的组织的 ID
setOrganismSlug(string) 组织的 slug，用于限制搜索到此组织 - 仅适用于公共 API
setPublic() 用于使用公共 API（可以接受布尔参数）
setPrivate() 用于使用私人 API（可以接受布尔参数）
addParam(string, string) 用于添加搜索参数
execute() 用于执行请求 返回 Api\Response
build() 用于返回请求 URL

方法可以链式调用（除了build()方法，它返回一个字符串）。例如：Query::create('payments')->setOrganimId('id')->execute()

API 响应

这是Api\V3\Response对象

方法

setResourceClass(string) : Api\Response：允许定义默认由getResource()使用的类。这个方法在Query类中用于当传递给构造函数的是一个类时。通过允许链式调用Query::create(RessouceClass::class)->[...]->execute()->throwException()->getResource()，可以避免重复和错误。
getHttpCode() : int : 返回 HTTP 状态码
getData() : stdClass：返回解码后的JSON数据
getPagination() : Api\Pagination：返回API返回的分页信息
getResource(string) : Resource：解析获取的数据为指定类别的资源。
isCollection() : boolean：用于判断响应是否为数据集合
isError() : boolean：用于判断响应是否为错误
getException() : Api\Exception：用于获取可能的异常
throwException() : Api\Response：用于抛出可能的异常。如果没有异常，返回Api\Response。这个方法允许与Query::execute()链式调用

查看 Query 和 Response 的使用示例

测试模式

此模式允许修改对象不可修改的属性，例如Callback\Payment::$action或Callback\Payment::$payment，或Api\Action::$organism，Api\Action::$payment，Api\Action::$campaign。

这允许在运行时重新定义它们以推送测试数据。

测试模式可以应用于HelloAsso的整体

HelloAsso\V3\HelloAsso::setTestMode(boolean)

它也可以独立地应用于回调和资源

HelloAsso\V3\Callback::setTestMode(boolean);
\HelloAsso\V3\Resource::setTestMode(boolean);

示例

支付回调

支付通知的响应示例

require_once 'helloasso/HelloAsso.php';

HelloAsso\HelloAsso::config("id-api", "password-api");
HelloAsso\HelloAsso::setTestMode(false);

$notification = HelloAsso\Callback::getPayment();
$organism  = $notification->getAction()->getOrganism()->name;
$campaign  = $notification->getAction()->getCampaign()->name;
$amount    = $notification->getPayment()->amount;
$firstname = $notification->getPayment()->payer_first_name;
$lastname  = $notification->getPayment()->payer_last_name;

echo "$firstname $lastname a payé la somme de $amount euros à $organism à l'occasion de la campagne : $campaign";

自定义请求和响应

获取年度支付记录

use HelloAsso\V3\Api\Query;
use HelloAsso\V3\Resource\Payment;

// Paiements de mon organisme depuis le début de l'année

$response = 
Query::create(Payment::class)
->setPage(1)                           // Premiere page 
->setResultsPerPage(50)                // 50 résultats par page
->addParam('from', date('Y').'-01-01') // Depuis le 1er janvier
->addParam('to', date('Y-m-d'))        // Jusqu'à aujourd'hui
->execute()                            // Exécute la requête
->throwException();                    // Lance l'exception si elle existe

$code       = $response->getHttpCode();
$pagination = $response->getPagination();
$paiements  = $response->getResource(Payment::class);

/*
 * Note : Puisqu'on a initialisé Query::create() avec le nom de la classe ("Payment::class"),
 * on peut aussi utiliser ici directement $response->getResource() sans paramètre 
 */
 
echo "Code HTTP resultat : $code" . PHP_EOL;
echo "Pagination : Page {$pagination->page} / {$pagination->$max_page} ({$pagination->result_per_page} résultats par page)" . PHP_EOL;

echo count($paiements) . ' paiements trouvés' . PHP_EOL;

var_export($paiements);

echo PHP_EOL;

开发

Francois Raoult

许可证

许可证MIT - 查看LICENSE

sarigue / helloasso

维护者

详细信息

README

先决条件

安装

处理 API v5

初始化

请求

资源列表：查询

单个记录：get()

所有记录：getAll()

刷新资源

回调

资源

资源的结构化数据

资源请求

API 响应

API v3 操作

使用方法

部分使用

对象列表

回调

资源

方法

API getter 方法

其他方法

请求和响应

自定义请求

API 响应

测试模式

示例

支付回调

自定义请求和响应

开发

许可证