philicevic/faceit-php

A PHP SDK for FACEITs api.

0.1.2 2026-04-07 00:39 UTC

Requires

• php: ^8.3
• saloonphp/saloon: ^4.0

Requires (Dev)

• laravel/pint: ^1.29
• pestphp/pest: ^4.4
• symfony/var-dumper: ^7.4

MIT

• Philipp Ehrenberg

README

A PHP SDK for the FACEIT Data API v4 built on Saloon v3. Returns fully typed, immutable DTOs for every endpoint.

This package is not stable yet. Use at your own risk.

Also, FACEITs API is sometimes inconsistent. This package tries to improve this a bit, but it still has its limitations. For example, the complete tournament endpoint is missing because I could not get reliable results from FACEIT.

Requirements

• PHP 8.3+

Installation

composer require philicevic/faceit-php

Getting a FACEIT API token

Create a server-side API key in the FACEIT Developer Portal and store it in an environment variable such as FACEIT_API_TOKEN.

Quick start

use Philicevic\FaceitPhp\Faceit;

$faceit = new Faceit($_ENV['FACEIT_API_TOKEN']);

// Look up a player by nickname
$player = $faceit->player()->lookup(nickname: 's1mple');

echo $player->nickname;
echo $player->country;
echo $player->games['cs2']->faceitElo;

// Get match details
$match = $faceit->match()->get('1-bb13fd78-e183-4d37-8a4b-ceed67da5265');

foreach ($match->teams as $team) {
    echo $team->name;
}

Laravel usage

See docs/laravel.md for service container binding and injection examples.

Resources

The client exposes one accessor per resource group. All methods return typed DTOs.

Accessor	Methods	Documentation
$faceit->player()	get, lookup, getBans, getGameStats, getMatches, getHubs, getStats, getTeams, getTournaments	docs/players.md
$faceit->match()	get, getStats	docs/matches.md
$faceit->championship()	list, get, getMatches, getResults, getSubscriptions	docs/championships.md
$faceit->hub()	get, getMatches, getMembers, getRoles, getRules, getStats	docs/hubs.md
$faceit->team()	get, getStats, getTournaments	docs/teams.md
$faceit->organizer()	getByName, get, getChampionships, getGames, getHubs, getTournaments	docs/organizers.md
$faceit->ranking()	getGlobal, getPlayer	docs/rankings.md
$faceit->leaderboard()	getChampionshipLeaderboards, getChampionshipGroupRanking, getHubLeaderboards, getHubRanking, get	docs/leaderboards.md
$faceit->game()	list, get	docs/games.md
$faceit->matchmaking()	get	docs/matchmakings.md
$faceit->search(...)	cross-entity search	docs/search.md

Paginated responses

Methods that return collections wrap items in a PaginatedResponse. See docs/paginated-responses.md.

Strict mode

Enable opt-in DTO validation to catch unexpected API changes early. See docs/strict-mode.md.

Error handling

The client uses Saloon and the AlwaysThrowOnErrors plugin, so HTTP errors surface as Saloon exceptions. Catch \Throwable or \Saloon\Exceptions\Request\RequestException as needed.

Testing

Built on Saloon's MockClient — no real HTTP calls needed in tests. See docs/testing.md.