PHPackages                             konsulting/justgiving-api-sdk - 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. konsulting/justgiving-api-sdk

ActiveLibrary[API Development](/categories/api)

konsulting/justgiving-api-sdk
=============================

A modern PHP SDK to communicate with the JustGiving API.

0.6.3(4y ago)43.2k↓100%2[1 issues](https://github.com/klever/justgiving-api-sdk/issues)MITPHP

Since Dec 14Pushed 2mo ago3 watchersCompare

[ Source](https://github.com/klever/justgiving-api-sdk)[ Packagist](https://packagist.org/packages/konsulting/justgiving-api-sdk)[ RSS](/packages/konsulting-justgiving-api-sdk/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (7)Dependencies (6)Versions (16)Used By (0)

JustGiving API SDK
==================

[](#justgiving-api-sdk)

[![Build Status](https://camo.githubusercontent.com/c427cee0252d54579d5f6cc7e839be0517c398ff6279765b8f4d0dd550a82981/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6b6c657665722f6a757374676976696e672d6170692d73646b2f6261646765732f6275696c642e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/klever/justgiving-api-sdk/build-status/master)[![Code Coverage](https://camo.githubusercontent.com/eef75e4c39b0de2391f0e615cf160ebe5989cde2029401a1711d0835584fd046/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6b6c657665722f6a757374676976696e672d6170692d73646b2f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/klever/justgiving-api-sdk/?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/5db2e598a97f9a5067665ab93c623febd866eff1b97571e326d92638a42d9ff8/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6b6c657665722f6a757374676976696e672d6170692d73646b2f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/klever/justgiving-api-sdk/?branch=master)

A PHP SDK for communicating with the JustGiving API. Based on the [original SDK](https://github.com/JustGiving/JustGiving.Api.Sdk) by [JustGiving and contributors](https://github.com/JustGiving/JustGiving.Api.Sdk/graphs/contributors).

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

[](#installation)

Install via composer:

```
composer require konsulting/justgiving-api-sdk

```

Quick start
-----------

[](#quick-start)

```
$auth = new AppAuth('abcde123');
$client = new JustGivingClient($auth);
```

```
$response = $client->account->isEmailRegistered('test@example.com');

if ($response->existenceCheck()) {
    echo 'An account has been registered with that email.';
}
```

```
$response = $client->charity->getById(2050);

if (! $response->wasSuccessful()) {
    throw new Exception(implode(', ', $response->errors));
}

$response->name;          // 'The Demo Charity1'
$response->websiteUrl;    // 'http://www.democharity.co.uk'
$response->pageShortName; // 'jgdemo'
```

See the [JustGiving API documentation](https://api.justgiving.com/docs) for more information.

Usage
-----

[](#usage)

### Setup

[](#setup)

The client requires an authentication object with your JustGiving API credentials. The available classes are:

- `AppAuth($appId, $secretKey = null)` for unprotected endpoints
    - **Note**: If JustGiving has generated a secret key for your app ID, you must include it here (even though the endpoints do not require authorisation). If not, just provide the app ID.
- `BasicAuth($appId, $username, $password)` for protected endpoints, where you have the username and password.
- `BearerAuth($appId, $secretKey, $token)` for protected endpoints, where you have a bearer token (from oAuth).

You may also pass in a [PSR-18](http://www.php-fig.org/psr/psr-18/) HTTP client as the second parameter. If this is not provided (or set to null), a default Guzzle client will be used.

The API base URL and version are set automatically, but may be overridden by passing an associative array with keys `root_domain` and `api_version` as the third argument.

For example:

```
$auth = new BasicAuth('abced123', 'user@example.com', 'pass123');
$httpClient = new \My\Own\Psr18Client;
$options = [
    'root_domain' => 'https://api.staging.justgiving.com',
    'api_version' => 2,
];

$client = new JustGivingClient($auth, $httpClient, $options);
```

### Querying the API

[](#querying-the-api)

The SDK defines a separate client class for each resource as define by the [API documentation](https://api.justgiving.com/docs), and each of those classes contain methods that correspond to API actions. To get a resource class, call the name of the resource as a property on the `$client` we built up earlier, for example `$client->account` or `$client->charity`. The relevant method is then called on top of that.

#### Method aliases

[](#method-aliases)

The actual methods on the class are named in camelCase and are often shortened from the original API action for brevity. However, there are aliases defined for every resource class so that the API action names may be used to interact with the SDK.

For example, both of these examples will work to get the status of a donation:

```
$client->donation->getStatus($donationId);                  // The actual method

$client->donation->RetrieveDonationStatus($donationId);     // The alias method that's the same as the API action name
```

#### Models

[](#models)

Some API actions (e.g. creating or updating resources) require a set of data grouped together in an object. To achieve this, a model class has been defined for each separate occasion when this is necessary, for example `Team` or `JoinTeamRequest`. These model classes all extend the parent `Model` class, which adds some useful functionality.

Data can be added to a model in several ways: it can be passed to the constructor as an array, passed to the `fill()` method as an array, or each property can be set individually. The `fill()` method may be used multiple times to set different properties, and will only override existing properties if they are explicitly passed in as an array item.

```
// Data set via constructor
$team = new Team([
    'name'      => 'My Team',
    'story'     => 'This is my story',
    'target'    => 1000,
]);

// Data set via fill() method
$team = new Team;
$team->fill([
    'name'      => 'My Team',
    'story'     => 'This is my story',
    'target'    => 1000,
]);

// Data set by setting public properties individually
$team = new Team;
$team->name = 'My Team';
$team->story = 'This is my story';
$team->target = 1000;
```

#### Custom API requests

[](#custom-api-requests)

The client allows custom requests via the `request()` method. This takes the HTTP method, the endpoint URI and any request options (e.g. headers). You may also override client options, for example the API version. These overrides will only apply for a single request.

For example, to perform a request to the beta campaign endpoint:

```
$endpoint = 'campaign/' . $campaignGUID;

$client->request('GET', $endpoint, [], ['api_version' => 2]);
```

If the endpoint requires a payload, JSON may be passed in as an HTTP option. A more complete example:

```
$client->request('POST', 'new-endpoint', [
        'headers' => ['x-custom-header' => 'custom'],
        'json'    => ['title' => 'The Title'],
    ], [
        'api_version' => 2,
        'root_domain' => 'https://api.staging.justgiving.com',
    ]);
```

### Working with responses

[](#working-with-responses)

The SDK returns an instance of `JustGivingApiSdk\Support\Response` from each request. This implements the [PSR-7](https://www.php-fig.org/psr/psr-7/) `ResponseInterface` and so allows access to the full HTTP response received by the client.

#### Response body

[](#response-body)

The raw response body can be accessed via

```
$response->getBody()->getContents()     // Returns the raw JSON response
```

However, the API returns JSON and so this method can prove to be an inefficient way of working with data. If `body` is accessed as a property on the response, the decoded JSON body is returned.

```
$response->body;                         // Returns the decoded response
```

From here, the response data is represented by arrays or objects of type `StdClass` which contain the data we want to use.

```
$result = $client->charity->getById(2050);
$result->body->name;            // 'The Demo Charity1'
$result->body->websiteUrl;      // 'http://www.democharity.co.uk'
$result->body->pageShortName;   // 'jgdemo'
```

The response class also allows body properties to be called directly on itself, i.e. the following is also valid:

```
$result = $client->charity->getById(2050);
$result->name;                  // 'The Demo Charity1'
$result->websiteUrl;            // 'http://www.democharity.co.uk'
$result->pageShortName;         // 'jgdemo'
```

#### Errors

[](#errors)

The API provides two formats of error message(s): the first is a general error message relating to the whole request (e.g. `That email address is already in use`), and the second is a list of error messages that relate to problems with specific parts of the request or data, with an identifier and description (e.g. ID: `FirstNameNotSpecified`, description `The FirstName field is required.`).

In the API documentation, the former is referred to as being the `errorMessage` property, and the latter refers to errors contained in `Error` objects (with properties `Error.id` and `Error.desc`).

Errors can be accessed via the `errors` property of the response object, which presents any errors present in a unified array format of `$identifier => $description`. If there is a general error, it is given the identifier `General` and added to the array like any other error. The reason phrase given with the response (accessible via the `getReasonPhrase()` method) is added to the errors array and given the identifier `ReasonPhrase`.

For example:

```
$response = $this->client->account->create(new CreateAccountRequest([
    'email'     => "john@example.com",
    'firstName' => "John",
    'lastName'  => "Smith",
    'password'  => 'password',
    'title'     => "Mr",
    'address' => new Address([
       'line1'             => "testLine1",
       'line2'             => "testLine2",
       'country'           => "United Kingdom",
       'countyOrState'     => "testCountyOrState",
       'townOrCity'        => "testTownOrCity",
       'postcodeOrZipcode' => "M130EJ",
    ]),

    'acceptTermsAndConditions' => false
]));

$errors = $response->errors;
// $errors is:
// [
//    'ReasonPhrase'                        => 'Validation errors occured.',
//    'FirstNameNotSpecified'               => 'The FirstName field is required.',
//    'AcceptTermsAndConditionsMustBeTrue'  => 'You must agree to the terms and conditions'
// ]
```

Now, say we correctly created that account and went to create a new account with the same email:

```
$response = $this->client->account->create(new CreateAccountRequest([
    'email'     => "john@example.com",
    'firstName' => "John",
    'lastName'  => "Smith",
    'password'  => 'password',
    'title'     => "Mr",
    'address' => new Address([
       'line1'             => "testLine1",
       'line2'             => "testLine2",
       'country'           => "United Kingdom",
       'countyOrState'     => "testCountyOrState",
       'townOrCity'        => "testTownOrCity",
       'postcodeOrZipcode' => "M130EJ",
    ]),

    'acceptTermsAndConditions' => true
]));

$errors = $response->errors;
// $errors is:
// [
//    'ReasonPhrase'    => 'Bad request',
//    'General'         => 'That email address is already in use'
// ]
```

#### Response helper methods

[](#response-helper-methods)

There are a couple of helper methods on the response to make some API calls and validation easier:

- `$response->wasSuccessful()` – returns true if the response has a status code of `2xx`.
- `$response->hasErrorMessages()` – returns true if the response has any error messages. **Note**: Some API actions do not return any error messages upon failure. This flag should be used to determine whether there is any useful error information to display, not to check if the action succeeded (use `wasSuccessful()` instead).
- `$response->existenceCheck()` – returns true if the response had a status code of 200, false if the status code is 404, and throws an exception otherwise. Useful for API calls that check for the existence of a resource.

###  Health Score

42

—

FairBetter than 89% of packages

Maintenance55

Moderate activity, may be stable

Popularity26

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 96.3% 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 ~271 days

Recently: every ~465 days

Total

12

Last Release

81d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4703657?v=4)[Konsulting](/maintainers/konsulting)[@konsulting](https://github.com/konsulting)

---

Top Contributors

[![rdarcy1](https://avatars.githubusercontent.com/u/15962421?v=4)](https://github.com/rdarcy1 "rdarcy1 (157 commits)")[![Keoghan](https://avatars.githubusercontent.com/u/6714599?v=4)](https://github.com/Keoghan "Keoghan (5 commits)")[![scrutinizer-auto-fixer](https://avatars.githubusercontent.com/u/6253494?v=4)](https://github.com/scrutinizer-auto-fixer "scrutinizer-auto-fixer (1 commits)")

---

Tags

apiapi-clientapi-wrapperjustgivingpsr-18psr-7sdk

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/konsulting-justgiving-api-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/konsulting-justgiving-api-sdk/health.svg)](https://phpackages.com/packages/konsulting-justgiving-api-sdk)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M647](/packages/sylius-sylius)[vluzrmos/slack-api

Wrapper for Slack.com WEB API.

102589.1k3](/packages/vluzrmos-slack-api)[ashallendesign/laravel-exchange-rates

A wrapper package for interacting with the exchangeratesapi.io API.

485677.8k](/packages/ashallendesign-laravel-exchange-rates)[smodav/mpesa

M-Pesa API implementation

16363.7k1](/packages/smodav-mpesa)[specialtactics/l5-api

Dependencies for the Laravel API Boilerplate package

3672.8k2](/packages/specialtactics-l5-api)[tamara-solution/php-sdk

Tamara PHP Client Library

10259.4k1](/packages/tamara-solution-php-sdk)

PHPackages © 2026

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