steffospieler/pronoundb

An API Wrapper for PronounDB.

v1.0.1 2024-07-08 15:44 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• pestphp/pest: ^2.34

MIT

• SteffoSpieler

README

API wrapper for the pronoundb.org API.

Setup

You need to create a client to be able to use the pronoundb wrapper. Make sure to use a descriptive user agent.

use Steffospieler\PronounDB\Client;

$client = new Client("Example for PHP PronounDB API Wrapper");

Examples

Lookup someone's pronouns by their discord id:

use Steffospieler\PronounDB\Client;
use Steffospieler\PronounDB\Platform;

$client = new Client("Example for PHP PronounDB API Wrapper");
$client->getPronounsByPlatformIds(Platform::Discord, 123456789012345678);
# -> {123456789012345678: ["he", "him"]}

Lookup someone's pronouns by their minecraft (java) uuid:

use Steffospieler\PronounDB\Client;
use Steffospieler\PronounDB\Platform;

$client = new Client("Example for PHP PronounDB API Wrapper");
$client->getPronounsByPlatformIds(Platform::Minecraft, "12345678-1234-1234-1234-123456789012")
# -> {"12345678-1234-1234-1234-123456789012": ["they", "them"]}

Lookup multiple users pronouns by their discord id:

use Steffospieler\PronounDB\Client;
use Steffospieler\PronounDB\Platform;

$client = new Client("Example for PHP PronounDB API Wrapper");
$client->getPronounsByPlatformIds(Platform::Discord, [123456789012345678, 987654321098765432])
# -> {123456789012345678: ["he", "him"], 987654321098765432: ["she", "her"]}

Supported Platforms

• Discord
• GitHub
• Minecraft (Java)
• Twitch
• Twitter

Custom Pronouns

You can give the client a list of pronouns to translate them.

use Steffospieler\PronounDB\Client;
use Steffospieler\PronounDB\Platform;

$client = new Client("Example for PHP PronounDB API Wrapper", [
    "unspecified" => [],
    "he" => ["Er", "Ihn"],
    "she" => ["Sie", "Ihr"],
    "it" => ["Es", "Seine"],
    "they" => ["They", "Them"],
    "any" => ["Jede"],
    "other" => ["Anderes"],
    "ask" => ["Frag"],
    "avoid" => ["Nutz Name"],
]);

$client->getPronounsByPlatformIds(Platform::Discord, 123456789012345678);
# -> {123456789012345678: ["Er", "Ihn"]}

You can also use one of the included translation pronouns (Translations::EnglishPronouns and Translations::GermanPronouns). AND when forgejo supports that, you can contribute translations as well! :D

⚠️ Notice, that currently in some languages some translations like the "They/Them" are still in active debate about how to translate them, so dear developer: Think about if the way the presets do it is good.

• If it's good, ignore the deprecation warning and use the preset.
• If not, make your own.

Decorations

Decorations are a new feature of pronoundb and currently in Beta. If you want to use them, you can do that like this:

use Steffospieler\PronounDB\Client;
use Steffospieler\PronounDB\Platform;

$client = new Client("Example for PHP PronounDB API Wrapper");
$client->getDecorationsByPlatformIds(Platform::Discord, 123456789012345678)
# -> {123456789012345678: "donator_aurora"}

Contributing

Contributions to this library are always welcome and highly encouraged.

License

This project is licensed under the MIT License - see the LICENSE file for details.