survos / global-giving-client

2.28.7 2026-09-15 10:39 UTC

Requires

• php: ^8.5
• ext-dom: *
• ext-xmlreader: *
• symfony/filesystem: ^8.1
• symfony/http-client: ^8.1
• symfony/property-access: ^8.1
• symfony/property-info: ^8.1
• symfony/serializer: ^8.1

Requires (Dev)

• phpunit/phpunit: ^13

MIT

Published on Packagist.org on 2026-09-15 10:40 UTC

README

A standalone PHP 8.5 client using Symfony HttpClient and Serializer components. Does not require a Symfony kernel.

use Survos\GlobalGiving\GlobalGivingClient;
use Survos\GlobalGiving\Enum\Export;
use Survos\GlobalGiving\Serialization\RecordMapper;
use Survos\GlobalGiving\Xml\ExportReader;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\Serializer\Encoder\XmlEncoder;

$mapper = new RecordMapper();
$client = new GlobalGivingClient(HttpClient::create(), $mapper, $apiKey);
$client->download(Export::ActiveProjects, '/data/active.xml');
$reader = new ExportReader(new XmlEncoder(), $mapper);
foreach ($reader->read('/data/active.xml', Export::ActiveProjects) as $project) {
    // typed scalar fields, optional typed organization, countries/themes collections.
    // Unknown provider data remains in $project->source.
}

Supported: active/all project and all organization bulk exports, featured projects, individual projects. Excludes payment/gift APIs, IATI, and retired all-project pagination. This is deliberately not a full SDK.

GlobalGivingException carries an optional HTTP status without including credentials or signed URLs. Download failures preserve the previous file. Signed URLs are refreshed once after a 403. Downloads are streamed and published atomically. The reader must be exhausted to validate record count and end-of-document. Consumers own snapshot retention, transactions and scheduling. Do not inject a client with credentials in global query defaults, because download requests go to a different host.

See docs/contract.md for provider documentation and observation date. Fixtures exercise scalar conversion, nested/optional fields, malformed XML, DTD rejection, download failures and signed-URL renewal. composer install && vendor/bin/phpunit runs the standalone tests; the app additionally runs kernel/import/UI tests.