PHPackages                             sarigue/helloasso - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. sarigue/helloasso

ActiveLibrary[API Development](/categories/api)

sarigue/helloasso
=================

Library to user HellAsso.com API

1.1.1(1y ago)0322MITPHPPHP >=5.6

Since Mar 13Pushed 1y ago2 watchersCompare

[ Source](https://github.com/sarigue/helloasso)[ Packagist](https://packagist.org/packages/sarigue/helloasso)[ RSS](/packages/sarigue-helloasso/feed)WikiDiscussions master Synced today

READMEChangelog (2)DependenciesVersions (4)Used By (0)

HelloAsso API and Notification callback
=======================================

[](#helloasso-api-and-notification-callback)

Bibliothèque pour utiliser les outils fournis par HelloAsso.com

- V3 : Manipulation de l'API v3
- V5 : Manipulation de l'API v5

Prerequis
---------

[](#prerequis)

- PHP 5.6
- Webserver (Apache, ...)
- Un compte HelloAsso.com
- Un accès API (clé + password) HelloAsso

Installation
------------

[](#installation)

Copier simplement le dossier contenant le code HelloAsso sur votre disque (ou cloner le dépôt)

---

Manipulation de l'API v5
------------------------

[](#manipulation-de-lapi-v5)

Version conseillée.

### Initialisation

[](#initialisation)

Initialiser la bibliothèque avec son client\_id et son client\_secret à l'aide de la classe HelloAsso puis appeler `authenticate()` pour lancer la requête d'autentification

```
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()
;
```

### Les requêtes

[](#les-requêtes)

Les `ResourceQuery` permettent d'effectuer une requête sur une ressource.

#### Liste de ressources : les Query

[](#liste-de-ressources--les-query)

Exemple de récupération d'une liste de paiements :

```
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;
```

#### Un seul enregistrement: get()

[](#un-seul-enregistrement-get)

Pour récupérer un seul enregistrement, on utilise la méthode `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);
```

#### Tous les enregistrements: getAll()

[](#tous-les-enregistrements-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;
```

#### Refresh d'une ressource

[](#refresh-dune-ressource)

Lorsqu'une ressource peut-être incomplète, par exemple lorsqu'elle vient d'une liste, d'une autre ressource, ou d'un *callback*, il peut être nécessaire d'effectuer une requête de type `get()`pour rafraichir ses données

```
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();
}
```

Ne pas faire de refresh() dans ces cas, a pour conséquence de n'avoir que des données partielles

### Callback

[](#callback)

Lorsque HelloAsso envoie une notification sur l'URL de callback spécifiée, les données concernant le payment / form / order sont transmises en POST dans le corps de la requête.

La classe `Callback` permet de traiter ces données pour récupérer la ressource

```
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
}
```

#### Ressources

[](#ressources)

Objets modélisant les données renvoyées par l'API

- \\HelloAsso\\V5\\Resource\\Payment - Un paiement
- \\HelloAsso\\V5\\Resource\\Organization - Infos sur la structure
- \\HelloAsso\\V5\\Resource\\Item - Item de vente
- \\HelloAsso\\V5\\Resource\\Form - Campagne (vente, adhésion, ...)
- \\HelloAsso\\V5\\Resource\\Order - Commande

##### Données structurées des ressources

[](#données-structurées-des-ressources)

- \\HelloAsso\\V5\\Data\\Payer - Informations payeur
- \\HelloAsso\\V5\\Data\\CustomField - Champ personnalisé
- \\HelloAsso\\V5\\Data\\CustomData - abstact - Liste de champs personnalisés
- \\HelloAsso\\V5\\Data\\User - Informations utilisateurs
- \\HelloAsso\\V5\\Data\\Meta - Informations de date création / modification
- \\HelloAsso\\V5\\Data\\Banner - Bannière de la campagne
- \\HelloAsso\\V5\\Data\\Amount - Infos montant : total, TVA, remise

##### Requêtes de ressources

[](#requêtes-de-ressources)

- \\HelloAsso\\V5\\Query\\Form
- \\HelloAsso\\V5\\Query\\Item
- \\HelloAsso\\V5\\Query\\Order
- \\HelloAsso\\V5\\Query\\Payment
- \\HelloAsso\\V5\\Query\\PaymentRefund - Extension de Payment permettant d'appeller la méthode refund()

#### Réponse API

[](#réponse-api)

Il s'agit de l'objet Api\\Response

Les méthodes

- `setResourceClass(string) : Api\Response` : Permet de définir la classe qui sera utilisée par défaut par `getResource()` et `getCollection()`. Utilisée pour l'usage générique de `ResourceQuery`.
- `getHttpCode() : int` : Retourne le code HTTP
- `isCollection() : boolean` : Si la réponse est une collection de resources
- `isError() : boolean` : Si la réponse est une erreur
- `throwException() : Api\Response` : Lancer l'exception éventuelle.
- `getException() : Api\ResponseError` : Retourne l'exception éventuelle
- `getData() : stdClass` : Données JSON décodées
- `getPagination() : Api\Pagination` : Pagination renvoyée par l'API
- `getResource(string) : Resource` : Retourne la ressource
- `getCollection(&Pagination) : Resource[]` : Retourne la liste de ressources

Voir les exemples pour l'utilisation de Query et Response

---

Manipulation de l'API v3
------------------------

[](#manipulation-de-lapi-v3)

Cette API est dépréciée

- HelloAsso.php est le point d'entrée et de configuration de l'API HelloAsso
- Callback.php et ses classes dérivées (dossier callback/) permet de manipuler les notifications
- Resource.php et ses classes dérivées (dossier resource/) permet de manipuler les ressources (objets)

### Utilisation

[](#utilisation)

Inclure simplement HelloAsso.php puis configurer l'API avec la clé.

```
require_once 'HelloAsso.php';

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

#### Utilisation partielle

[](#utilisation-partielle)

Il est possible de n'utiliser que la partie API / Ressources HelloAsso et utiliser moins de fichier

Inclure alors seulement Resource.php et supprimer le dossier callback/ et le fichier Callback.php et HelloAsso.php

La configuration se fait alors en définissant les variables statiques `\HelloAsso\Api\Query::setDefaultAuth($api_id, $api_pass)`;

```
require_once 'Resource.php';

use HelloAsso\Api\Query;

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

### Liste des objets

[](#liste-des-objets)

#### Callback

[](#callback-1)

Objets modélisant les données transmises lors de la réception d'une notification HelloAsso

- \\HelloAsso\\V3\\Callback\\Campaign : Notification de création/édition d'une campagne
- \\HelloAsso\\V3\\Callback\\Payment : Notification de paiement

Les méthodes :

- \\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

#### Ressources

[](#ressources-1)

Objets modélisant les données renvoyées par l'API

- \\HelloAsso\\V3\\Resource\\BasicCampaign : Campagne basique (information publique)
- \\HelloAsso\\V3\\Resource\\Action
- \\HelloAsso\\V3\\Resource\\Campaign
- \\HelloAsso\\V3\\Resource\\Payment
- \\HelloAsso\\V3\\Resource\\Organism

### Les méthodes

[](#les-méthodes)

#### Methodes getter API

[](#methodes-getter-api)

Chaque ressource (sauf BasicCampaign) possède les méthodes statiques suivantes:

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

BasicCampaign dispose des méthodes de recherche statiques

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

pour le recherche des campagne d'un organisme donné par son slug et

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

pour le recherche des campagne d'un organisme donné par son id

#### Autres méthodes

[](#autres-méthodes)

Une action est liée à un paiement, une campagne et un organisme. Les méthodes getters sont donc disponibles :

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

### Requête et réponse

[](#requête-et-réponse)

#### Requête personnalisée

[](#requête-personnalisée)

Pour créer et exécuter une requête d'API personnalisée, utiliser la classe \\HelloAsso\\Api\\Query

Les paramètres du constructeur sont :

- string ressource : La ressource à chercher, ou bien le nom (full-qualified. utiliser ::class) de la classe ressource
- string id (facultatif) : l'ID de la ressource à récupérer

Les méthodes :

- Methode statique `Query::create(string ressource[, string id])` pour récupérer une nouvelle requete
- `setId(string)` pour l'ID de la ressource à récupérer
- `setPage(int)` le numéro de page à récupérer
- `setResultsPerPage(int)` le nombre de résultat par pages
- `setCampaignId(string)` id de la campagne sur laquelle limiter la recherche
- `setOrganismId(string)` id de l'organisme sur lequel limiter la recherche
- `setOrganismSlug(string)` slug de l'organisme pour limiter la recherche à cet organisme - **uniquement pour l'API publique**
- `setPublic()` pour utiliser l'API publique (prend éventuellement le booléen en paramètre)
- `setPrivate()` pour utiliser l'API privé (prend éventuellement le booléen en paramètre)
- `addParam(string, string)` pour ajouter des paramètres de recherche
- `execute()` pour exécuter la requête **retourne une Api\\Response**
- `build()` pour retourner l'URL de requête depuis les éléments donnés

Les méthodes sont chaînables (sauf build() qui retourne une chaine de caractère). Par exemple : `Query::create('payments')->setOrganimId('id')->execute()`

#### Réponse API

[](#réponse-api-1)

Il s'agit de l'objet Api\\V3\\Response

Les méthodes

- `setResourceClass(string) : Api\Response` : Permet de définir la classe qui sera utilisée par défaut par `getResource()`. Cette fonction est utilisée par la classe `Query` lorsque c'est une classe qui est passée au constructeur. Permet d'éviter la répétion et les erreurs en permettant de chaîner `Query::create(RessouceClass::class)->[...]->execute()->throwException()->getResource()`
- `getHttpCode() : int` : Retourne le code HTTP
- `getData() : stdClass` : Retourne les données JSON décodées
- `getPagination() : Api\Pagination` : Retourne la pagination renvoyée par l'API
- `getResource(string) : Resource` : Parse les données récupérée comme la ressource de classe donnée.
- `isCollection() : boolean` : Pour savoir si la réponse est une collection de donnée
- `isError() : boolean` : Pour savoir si la réponse est une erreur
- `getException() : Api\Exception` : Pour récupérer l'exception éventuelle
- `throwException() : Api\Response` : Pour lancer l'exception éventuelle. Si pas d'exception, retourne Api\\Response. Cette méthode permet de chainer avec Query::execute()

Voir les exemples pour l'utilisation de Query et Response

### Mode test

[](#mode-test)

Ce mode permet de modifier les propriétés non modifiables des objets telles que Callback\\Payment::$action ou Callback\\Payment::$payment ou encore Api\\Action::$organism, Api\\Action::$payment, Api\\Action::$campaign

Cela permet de les redéfinir à la volée pour pousser des données de test.

Le mode test peut se définir pour l'ensemble de HelloAsso

```
HelloAsso\V3\HelloAsso::setTestMode(boolean)
```

Il peut aussi se définir indépendamment pour le callback et les resources

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

### Exemple

[](#exemple)

#### Callback de paiement

[](#callback-de-paiement)

Exemple de réaction à la notification d'un paiement

```
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";
```

#### Requête personnalisée et réponse

[](#requête-personnalisée-et-réponse)

Récupérer les paiements de l'année

```
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;
```

### Developpement

[](#developpement)

- Francois Raoult

### Licence

[](#licence)

Licence MIT - Voir [LICENSE](LICENSE)

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance43

Moderate activity, may be stable

Popularity8

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 66.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~378 days

Total

3

Last Release

451d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/15203034?v=4)[Sarigue](/maintainers/sarigue)[@sarigue](https://github.com/sarigue)

---

Top Contributors

[![sarigue](https://avatars.githubusercontent.com/u/15203034?v=4)](https://github.com/sarigue "sarigue (2 commits)")[![jngermon](https://avatars.githubusercontent.com/u/12733304?v=4)](https://github.com/jngermon "jngermon (1 commits)")

### Embed Badge

![Health badge](/badges/sarigue-helloasso/health.svg)

```
[![Health](https://phpackages.com/badges/sarigue-helloasso/health.svg)](https://phpackages.com/packages/sarigue-helloasso)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k15](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)