PHPackages                             jan-wennrich/bgg-api - 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. jan-wennrich/bgg-api

ActiveLibrary[API Development](/categories/api)

jan-wennrich/bgg-api
====================

BoardGameGeek.com API Client Library

0.2.0(4mo ago)07.0k↑671.4%1[4 issues](https://github.com/JanWennrich/bgg-api/issues)1MITPHPPHP ^8.2CI failing

Since Dec 31Pushed 4mo agoCompare

[ Source](https://github.com/JanWennrich/bgg-api)[ Packagist](https://packagist.org/packages/jan-wennrich/bgg-api)[ RSS](/packages/jan-wennrich-bgg-api/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (3)Dependencies (33)Versions (5)Used By (1)

jan-wennrich/bgg-api
====================

[](#jan-wennrichbgg-api)

[![Logo](/README-logo.webp)](/README-logo.webp)

[![Packagist Version](https://camo.githubusercontent.com/3b66058e131abacc0016cea5d8366f22471fe41177d6c4ca22c5f56f89709e0c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a616e2d77656e6e726963682f6267672d617069)](https://packagist.org/packages/jan-wennrich/bgg-api)[![Packagist Downloads](https://camo.githubusercontent.com/eef8661be7c0b88886c22ed3e47a6a1c0e999abbffd2550d4310e878540bf126/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a616e2d77656e6e726963682f6267672d617069)](https://packagist.org/packages/jan-wennrich/bgg-api)[![PHP Version Require](https://camo.githubusercontent.com/0aa5cf02a3d31d60546a48ddb44aafefd18ec91d98e8ccb3a660d48ec98b287e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6a616e2d77656e6e726963682f6267672d617069)](https://packagist.org/packages/jan-wennrich/bgg-api)[![License](https://camo.githubusercontent.com/036111c25e95102e060ffbb6f7ecf4858a7e4cf0ad5bfbac1bd17bbb59468c63/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a616e2d77656e6e726963682f6267672d617069)](https://github.com/JanWennrich/bgg-api/blob/main/LICENSE)[![CI Status](https://github.com/JanWennrich/bgg-api/actions/workflows/test.yml/badge.svg)](https://github.com/JanWennrich/bgg-api/actions)

A modern **PHP API client library** for [BoardGameGeek.com](https://boardgamegeek.com) using the **XML API2**.

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

[](#installation)

Require the package with Composer:

```
composer require jan-wennrich/bgg-api
```

Usage
-----

[](#usage)

### Creating the client

[](#creating-the-client)

Quickstart:

```
use JanWennrich\BoardGameGeekApi\Client;

$client = Client::autocreate();
```

This creates a `Client` instance with sane defaults, suitable for most users.

Alternatively you may use the constructor to configure the client to your needs. You may pass:

- a custom **PSR-18 HTTP client** plus **PSR-17 request/stream factories**
- a `\JanWennrich\BoardGameGeekApi\RetryConfig` to configure retry behavior
- a custom User-Agent string
- a `Psr\Log\LoggerInterface`

### Authentication

[](#authentication)

Recently the BoardGameGeek API requires authentication to access it.

You must authenticate via an BoardGameGeek [API token](https://boardgamegeek.com/using_the_xml_api) (recommended) or a BoardGameGeek username & password.

#### API Token

[](#api-token)

An API Token can be obtained from BoardGameGeek: [https://boardgamegeek.com/using\_the\_xml\_api](https://boardgamegeek.com/using_the_xml_api)

```
$client->setAuthorization($apiToken);
```

#### Username & Password

[](#username--password)

Important

Authenticating via username & passwords limits the access to resources of the given username.
So you can access the user's collection or plays for example but no general resources like boardgames.

```
$client->login($username, $password);
```

The login is stored during runtime, so you have to log in again after the program terminates.

### Endpoints

[](#endpoints)

#### Things (BoardGames)

[](#things-boardgames)

To get a single `Thing` you can use the following method:

```
$client->getThing(string $id, bool $stats = false, bool $versions = false): ?Thing
```

To get multiple `Things` at once, use the following method:

```
$client->getThings(array $ids, bool $stats = false, bool $versions = false): Thing[]
```

A single `Thing` provides the following API:

- Basic info:
    - `getId()`, `getType()`, `isType($type)`
    - `getName()`, `getDescription()`
    - `getImage()`, `getThumbnail()`
    - `getYearPublished()`
    - `getMinPlayers()`, `getMaxPlayers()`
    - `getPlayingTime()`, `getMinPlayTime()`, `getMaxPlayTime()`
    - `getMinAge()`
- Links & related entities:
    - `getBoardgameCategories()`, `getBoardgameMechanics()`
    - `getBoardgameDesigners()`, `getBoardgameArtists()`, `getBoardgamePublishers()`
    - `getBoardgameExpansions()`
    - `getBoardgameVersions()`
    - `getLinks()` (raw link objects)
    - `getAlternateNames()`
    - `getBoardgameBasegame()`
- Stats (if `stats=true` when requesting the `Thing`):
    - `getRatingAverage()`
    - `getWeightAverage()`
    - `getRank()`
    - `getLanguageDependenceLevel()`

*Example: Get the thumbnails of "Ark Nova" (ID `342942`) and "Gloomhaven" (ID `174430`)*

```
$things = $client->getThings([342942, 174430]);

foreach ($things as $thing) {
    echo $thing->getThumbnail() . PHP_EOL;
}
```

#### Search

[](#search)

To search for something you can use the following method:

```
$client->search(string $query, bool $exact = false, string $type = Type::BOARDGAME): Search\Query
```

Each item in the `Seach\Query` is a `Search\Result` with:

- `getId()`, `getType()`, `isType($type)`
- `getName()`
- `getYearPublished()`

*Example: Search for the board game "Terraforming Mars" and list the names of search results*

```
use JanWennrich\BoardGameGeekApi\Type;

$query = $client->search('Terraforming Mars', exact: true, type: Type::BOARDGAME);

echo count($query) . PHP_EOL;

$first = $query[0];
if ($first) {
    echo $first->getName() . PHP_EOL;
}
```

#### Hot items

[](#hot-items)

To get hot items you can use this method:

```
$client->getHotItems(string $type = Type::BOARDGAME): HotItem[]
```

A `HotItem` provides these getters:

- `getId()`
- `getRank()`
- `getName()`
- `getYearPublished()`
- `getThumbnail()`

*Example: Get hot items and list their ranks and names*

```
$hot = $client->getHotItems();
foreach ($hot as $item) {
    echo $item->getRank() . ': ' . $item->getName() . PHP_EOL;
}
```

#### User

[](#user)

To get a use you can use this method:

```
$client->getUser(string $name): ?User
```

A `User` provides the following getters:

- `getId()`, `getLogin()`, `getName()`
- `getFirstName()`, `getLastName()`
- `getAvatar()`, `getCountry()`
- `getYearRegistered()`

*Example: Get the avatar of user "Klabauterjan"*

```
$user = $client->getUser('Klabauterjan');
echo $user->getAvatar();
```

#### Collection

[](#collection)

To get a collection, you can use this method:

```
$client->getCollection(array $parameters): Collection
```

All parameters as specified by the BoardGameGeek API are supported: [https://boardgamegeek.com/wiki/page/BGG\_XML\_API2#toc13](https://boardgamegeek.com/wiki/page/BGG_XML_API2#toc13)

Each entry of a Collection is a `Collection\Item` with these getters:

- object info: `getObjectType()`, `getObjectId()`, `getSubtype()`, `getCollId()`
- metadata: `getName()`, `getYearPublished()`, `getImage()`, `getThumbnail()`
- stats: `getNumPlays()`, `getRatingAverage()`
- players/time: `getMinPlayers()`, `getMaxPlayers()`, `getPlayingTime()`, `getMinPlayTime()`, `getMaxPlayTime()`
- status: `getStatus(): Collection\ItemStatus`

A `Collection\ItemStatus` provides this API:

- flags: `isOwn()`, `isPrevOwned()`, `isForTrade()`, `isWant()`, `isWantToPlay()`, `isWantToBuy()`, `isWishlist()`, `isPreordered()`
- wishlist info: `getWishlistPriority()`
- timestamps: `getLastModified()`

*Example: Get all boardgames owned by user "Klabauterjan" and list them with their name and publish date*

```
$collection = $client->getCollection([
    'username' => 'Klabauterjan',
    'owned' => 1,
    'stats' => 1
]);

echo $collection->count() . PHP_EOL;

foreach ($collection as $item) {
    echo $item->getName() . PHP_EOL;
    echo $item->getYearPublished() . PHP_EOL;
}
```

#### Plays

[](#plays)

To get plays, you can use this method:

```
$client->getPlays(array $parameters): Play[]
```

All parameters as specified by the BoardGameGeek API are supported: [https://boardgamegeek.com/wiki/page/BGG\_XML\_API2#toc12](https://boardgamegeek.com/wiki/page/BGG_XML_API2#toc12)

A `Play` object provides these getters:

- core: `getId()`, `getDate()`, `getQuantity()`, `getLength()`
- flags: `isIncomplete()`, `isNoWinStats()`
- location/comments: `getLocation()`, `getComments()`
- item info: `getObjectType()`, `getObjectId()`, `getObjectName()`, `getSubtypes()`
- players: `getPlayers(): Player[]`

A `Player` object provides these getters:

- identity: `getUsername()`, `getUserid()`, `getName()`
- game info: `getStartPosition()`, `getColor()`, `getScore()`, `getRating()`
- flags: `isNew()`, `isWin()`

*Example: Get plays of user "Klabauterjan" and list their date, name of the game and the names of players*

```
$plays = $client->getPlays(['username' => 'Klabauterjan']);

foreach ($plays as $play) {
    echo $play->getDate() . ' - ' . $play->getObjectName() . PHP_EOL;

    foreach ($play->getPlayers() as $player) {
        echo '  - ' . ($player->getName() ?: $player->getUsername()) . PHP_EOL;
    }
}
```

### Reliability / Retries

[](#reliability--retries)

The BoardGameGeek API does not immediately provide results to most requests.
Instead it returns a `HTTP 202` response and will return the actual data with a later request.

To simplify this, the client has built-in retry behavior when fetching data:

- Retries up to **3 times**
- Waits **5 seconds** between attempts by default (configurable)
- Automatically retries when BGG responds with **HTTP 202** (queued response)
- Retries on transport errors and **5xx** responses
- Does **not** keep retrying on typical **4xx** client errors (e.g. missing authentication)

If all attempts fail, an `Exception` is thrown.

You can customize retry behavior via `RetryConfig`:

```
use JanWennrich\BoardGameGeekApi\Client;
use JanWennrich\BoardGameGeekApi\RetryConfig;

$client = Client::autocreate(
    retryConfig: new RetryConfig(
        maxAttempts: 5,
        initialExponentialRetryDelayInSeconds: 1,
    )
);
```

Testing & Development
-------------------------

[](#testing--development)

To develop/test this library, do the following:

1. Clone the repository
2. Install dependencies (`composer install`)

Tests can be executed by calling:

```
composer test
```

To opt in to live API tests, the following environment variables with credentials have to be set, when running `composer test`:

- `BGG_AUTH_TOKEN`
- `BGG_USERNAME`
- `BGG_PASSWORD`

### Fixture Recording

[](#fixture-recording)

To capture real API responses as XML fixtures, use the fixture recorder command:

```
BGG_AUTH_TOKEN=... BGG_USERNAME=... BGG_PASSWORD=... php tests/record-fixtures.php
```

The recorder writes fixtures into `tests/fixtures//` and requires all three environment variables to be set.

The library uses the following tools to ensure functionality & stability:

- [PHPUnit](https://github.com/sebastianbergmann/phpunit) for testing
- [PHPStan](https://github.com/phpstan/phpstan) for static analysis
- [PHP CS Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer) to enforce code style
- [Rector](https://github.com/rectorphp/rector) for automated refactorings
- [Composer Dependency Analyser](https://github.com/shipmonk-rnd/composer-dependency-analyser) for finding unused or unspecified requirements
- GitHub Actions CI for automatic testing

Credits
-------

[](#credits)

This library is a fork of [castro732/bggxmlapi2](https://github.com/castro732/bggxmlapi2) which is a fork of [nataniel/bggxmlapi2](https://github.com/nataniel/bggxmlapi2).
Thanks to the original authors for the foundation.

The XML Schema (`.xsd`) files in `tests/xsd/` were taken from [tnaskali/bgg-api](https://github.com/tnaskali/bgg-api).

License
-------

[](#license)

MIT License

See [`LICENSE`](/LICENSE) for details.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance77

Regular maintenance activity

Popularity26

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 77.9% 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 ~30 days

Total

3

Last Release

126d ago

PHP version history (2 changes)0.1.0PHP ^8.0

0.2.0PHP ^8.2

### Community

Maintainers

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

---

Top Contributors

[![JanWennrich](https://avatars.githubusercontent.com/u/42703348?v=4)](https://github.com/JanWennrich "JanWennrich (180 commits)")[![nataniel](https://avatars.githubusercontent.com/u/411846?v=4)](https://github.com/nataniel "nataniel (33 commits)")[![castro732](https://avatars.githubusercontent.com/u/1149801?v=4)](https://github.com/castro732 "castro732 (13 commits)")[![pimpeters](https://avatars.githubusercontent.com/u/9702432?v=4)](https://github.com/pimpeters "pimpeters (2 commits)")[![alberto-bottarini](https://avatars.githubusercontent.com/u/1442934?v=4)](https://github.com/alberto-bottarini "alberto-bottarini (1 commits)")[![Rocksheep](https://avatars.githubusercontent.com/u/1311371?v=4)](https://github.com/Rocksheep "Rocksheep (1 commits)")[![titich](https://avatars.githubusercontent.com/u/36174849?v=4)](https://github.com/titich "titich (1 commits)")

---

Tags

apibggbgg-apibgg-libboardgamegeekclientphp

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/jan-wennrich-bgg-api/health.svg)

```
[![Health](https://phpackages.com/badges/jan-wennrich-bgg-api/health.svg)](https://phpackages.com/packages/jan-wennrich-bgg-api)
```

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35789.4k2](/packages/telnyx-telnyx-php)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[sylius/sylius

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

8.5k5.9M739](/packages/sylius-sylius)[deeplcom/deepl-php

Official DeepL API Client Library

2607.3M115](/packages/deeplcom-deepl-php)[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k28.0M318](/packages/openai-php-client)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)

PHPackages © 2026

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