README

A PHP 8.3+ library for accessing NBA API endpoints — live games, box scores, play-by-play, standings, player stats, and more. Responses are normalized into readable arrays (and typed DTOs where available) so you get clean data without parsing raw API payloads yourself.

Table of contents / index

Installing
Requirements
How it works
Fetching data
Error handling
Debugging
Custom HTTP client
Response caching
Typed DTOs
Helpers
Testing & development
Today's games
Game time seconds formatted
Box score
Play by play
Play by play V3
Play by play V2
Play by play V1
Play by play clips
Rotations
Game summary
Tradition box score
Scoring box score
Defensive box score
Hustle box score
Game matchups
Usage box score
4 factors box score
Advanced box score
Tracking box score
Team lineups
Team shots dash
Standings
League game log
Team year over year
Team roster
Team info
Team game logs
Team franchise players
Schedule
Player on off
Player year over year
Player shooting
Player
Player awards
Player career
Playoff brackets
Playoff picture
Playoff series
Team
Teams years
League leaders
League player match ups
League player shot locations
League player shots
Video events
Player game logs
Player compare
Player next games
Player vs player
Player index
Shot chart
Draft history
Draft combine
Franchise history
Franchise leaders
All-time leaders
Team historical leaders
Team dashboard
Win probability
Player clutch stats
Team clutch stats
League hustle stats
League game finder
Player fantasy profile
Team game streak finder
Player estimated metrics

Installing

Install with Composer:

composer require corbpie/nba-live

Requirements

PHP 8.3+
ext-curl
ext-json
psr/simple-cache (installed automatically; bring your own cache implementation for response caching)

How it works

Every NBA endpoint is a class under the Corbpie\NBALive namespace. Each class:

Extends NBABase and implements FetchableEndpoint
Exposes a fetch() method that calls the NBA API and populates public properties
Normalizes raw API responses into easy-to-use arrays (and typed DTOs where available)

Two API sources are used:

Source	Used for	Example
`cdn.nba.com`	Live data (box scores, play-by-play, scoreboard)	`NBABoxScore`, `NBAToday`
`stats.nba.com`	Historical stats, standings, player data	`NBAStandings`, `NBAPlayerCareer`

Fetching data

All endpoints use a consistent fetch() pattern. Constructors still auto-fetch for backward compatibility when you pass parameters, but the recommended approach is to configure properties and call fetch() explicitly.

Explicit fetch (recommended):

use Corbpie\NBALive\NBATeamGameLogs;

$logs = new NBATeamGameLogs();
$logs->team_id = 1610612754;
$logs->season = NBATeamGameLogs::CURRENT_SEASON;
$logs->fetch();

foreach ($logs->games as $game) {
    echo $game['pts'];
}

Constructor auto-fetch (still supported):

use Corbpie\NBALive\NBAStandings;

// Fetches immediately on construction
$standings = new NBAStandings('2025-26');

Lazy fetch with game ID endpoints:

use Corbpie\NBALive\NBABoxScore;

// No API call yet
$box = new NBABoxScore();
$box->fetch('0022500123');

// Or pass the game ID in the constructor (auto-fetches)
$box = new NBABoxScore('0022500123');

Error handling

API failures throw NBAApiException. Transport errors (timeouts, cURL failures) and invalid JSON are also surfaced as exceptions.

use Corbpie\NBALive\NBAApiException;
use Corbpie\NBALive\NBABoxScore;

try {
    $boxscore = new NBABoxScore('invalid_game_id');
} catch (NBAApiException $e) {
    echo 'API Error: ' . $e->getMessage();
    echo 'HTTP Code: ' . $e->getHttpCode();
    print_r($e->getResponseBody()); // Decoded response body, if available
}

Debugging

After any API call, debug metadata is available on the endpoint instance:

$standings = new NBAStandings();
$standings->fetch();

echo $standings->url;            // Final URL used
echo $standings->response_code;  // HTTP status code
echo $standings->response_size;  // Response size in bytes
echo $standings->connect_time;   // Connection time in seconds
echo $standings->ip;             // IP of the API endpoint

Custom HTTP client

Inject a custom HTTP client for testing, custom timeouts, or swapping the transport layer. All endpoint constructors accept an optional NbaHttpClientInterface as the last argument.

use Corbpie\NBALive\Http\CurlNbaHttpClient;
use Corbpie\NBALive\NBAToday;

$client = new CurlNbaHttpClient(
    connectTimeout: 5,
    totalTimeout: 20,
);

$today = new NBAToday($client);

Available HTTP classes:

Class	Purpose
`CurlNbaHttpClient`	Default cURL transport (10s connect / 30s total timeout)
`CachingNbaHttpClient`	PSR-16 caching decorator (see below)
`NbaHttpResponse`	Immutable response DTO returned by the client

For unit tests, mock the client:

use Corbpie\NBALive\Http\NbaHttpClientInterface;
use Corbpie\NBALive\Http\NbaHttpResponse;

final class MockClient implements NbaHttpClientInterface
{
    public function get(string $url): NbaHttpResponse
    {
        return new NbaHttpResponse(
            url: $url,
            statusCode: 200,
            body: '{"scoreboard":{"games":[]}}',
            size: 28,
            connectTime: 0.01,
            ip: '127.0.0.1',
        );
    }
}

$today = new NBAToday(new MockClient());

Response caching

Wrap any HTTP client with CachingNbaHttpClient to cache successful responses. Pass any PSR-16 CacheInterface implementation (Redis, filesystem, in-memory, etc.).

use Corbpie\NBALive\Http\CachingNbaHttpClient;
use Corbpie\NBALive\Http\CurlNbaHttpClient;
use Corbpie\NBALive\NBAStandings;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

$cache = new Psr16Cache(new FilesystemAdapter(namespace: 'nba-live'));
$cachedClient = new CachingNbaHttpClient(
    inner: new CurlNbaHttpClient(),
    cache: $cache,
    defaultTtl: 300, // 5 minutes
);

// Standings are cached; repeat calls within TTL skip the network
$standings = new NBAStandings('2025-26', $cachedClient);

Suggested TTLs:

Data type	Suggested TTL
Standings, rosters	5–15 minutes
Live box scores, play-by-play	5–15 seconds
Historical stats, career data	1–24 hours

Typed DTOs

Selected endpoints expose readonly DTO objects alongside the legacy array properties. DTOs provide typed access; toArray() returns the same shape as the array properties for backward compatibility.

Endpoint	DTO property	Array property	DTO class
`NBATeamGameLogs`	`$gameLogs`	`$games`	`TeamGameLog`
`NBAStandings`	`$standingEntries`	`$standings`	`TeamStanding`
`NBALeagueGameFinder`	`$gameEntries`	`$games`	`LeagueGameEntry`

use Corbpie\NBALive\NBATeamGameLogs;

$logs = new NBATeamGameLogs();
$logs->team_id = 1610612754;
$logs->fetch();

// Typed access
foreach ($logs->gameLogs as $entry) {
    echo $entry->pts;      // int|float
    echo $entry->wasWin;   // bool
    echo $entry->matchup;  // string
}

// Legacy array access (unchanged)
foreach ($logs->games as $game) {
    echo $game['pts'];
}

Custom HTTP client

Inject a custom client for testing or to swap the transport layer:

use Corbpie\NBALive\Http\CachingNbaHttpClient;
use Corbpie\NBALive\Http\CurlNbaHttpClient;
use Corbpie\NBALive\NBABoxScore;
use Psr\SimpleCache\CacheInterface;

$boxScore = new NBABoxScore();
$boxScore->fetch('0022500123');

$cachedClient = new CachingNbaHttpClient(
    inner: new CurlNbaHttpClient(),
    cache: $cacheImplementation,
    defaultTtl: 300,
);

Explicit fetch()

All endpoints now expose a fetch() method. Constructors still auto-fetch for backward compatibility when parameters are provided, but you can also configure properties and call fetch() manually:

$logs = new NBALive\NBATeamGameLogs();
$logs->team_id = 1610612754;
$logs->fetch();

Helpers

Season and utility constants on NBABase:

use Corbpie\NBALive\NBABase;
use Corbpie\NBALive\Season;

NBABase::CURRENT_SEASON;  // e.g. '2025-26'
NBABase::PREVIOUS_SEASON; // e.g. '2024-25'
NBABase::CURRENT_TYPE;    // 'Regular+Season'

// Dynamic season resolution (NBA season starts in October)
Season::current();   // Resolves from today's date
Season::previous();

// Mode types
NBABase::MODE_PER_GAME;
NBABase::MODE_TOTAL;
NBABase::MODE_PER48;

// Season types
NBABase::TYPE_REGULAR;
NBABase::TYPE_PLAY_IN;
NBABase::TYPE_PLAYOFFS;
NBABase::TYPE_ALL_STAR;
NBABase::TYPE_PRE_SEASON;

// Game status constants
NBABase::GAME_STATUS_NOT_STARTED; // 1
NBABase::GAME_STATUS_IN_PROGRESS; // 2
NBABase::GAME_STATUS_COMPLETED;   // 3

// Player status constants
NBABase::STATUS_INACTIVE;
NBABase::STATUS_ACTIVE;

// Time constants (in seconds)
NBABase::QUARTER_DURATION_SECONDS; // 720 (12 minutes)
NBABase::OT_DURATION_SECONDS;      // 300 (5 minutes)

// Game clock formatting
NBABase::secondsToFormattedGameTime(800);

Testing & development

composer test     # Run PHPUnit (31 tests)
composer analyse  # Run PHPStan static analysis (level 5)

CI runs on GitHub Actions against PHP 8.3 and 8.4.

Todays games and live

use Corbpie\NBALive\NBAToday;

$today = new NBAToday(); // Auto-fetches today's scoreboard

// Game lists by status
$today->all_games;
$today->live_games;
$today->upcoming_games;
$today->completed_games;

// Summary counts
$today->summary; // date, all_games, live_games, completed_games, upcoming_games

// Format raw game data into a readable structure
$formatted = $today->gameFormatter($today->live_games);

Game time seconds formatted (Helper function)

use Corbpie\NBALive\NBABase;

NBABase::secondsToFormattedGameTime(800);

Outputs

{
  "period": 2,
  "period_string": "Q2",
  "seconds": 800,
  "seconds_period": 80,
  "seconds_period_string": "10:40",
  "full_string": "Q2 10:40"
}

Boxscore

NBA API Live CDN box score version.

use Corbpie\NBALive\NBABoxScore;

// Auto-fetch via constructor
$boxscore = new NBABoxScore('0022500123');

// Or fetch explicitly
$boxscore = new NBABoxScore();
$boxscore->fetch('0022500123');

// Or set game_id then fetch
$boxscore = new NBABoxScore();
$boxscore->game_id = '0022500123';
$boxscore->fetch();

// Team and player data
$boxscore->home_team;
$boxscore->away_team;
$boxscore->home_players;
$boxscore->away_players;

// Sort players by a stat key
$boxscore->sortAsc($boxscore->home_players, 'points');
$boxscore->sortDesc($boxscore->home_players, 'points');

// Inactive players for both teams
$boxscore->getInactive();

Team example:

{
  "assists": 12,
  "assistsTurnoverRatio": 0.857142857142857,
  "benchPoints": 23,
  "biggestLead": 0,
  "biggestScoringRun": 9,
  "biggestScoringRunScore": "77-75",
  "blocks": 3,
  "blocksReceived": 2,
  "fastBreakPointsAttempted": 6,
  "fastBreakPointsMade": 3,
  "fastBreakPointsPercentage": 0.5,
  "fieldGoalsAttempted": 59,
  "fieldGoalsEffectiveAdjusted": 0.440677966101695,
  "fieldGoalsMade": 23,
  "fieldGoalsPercentage": 0.38983050847457595,
  "foulsOffensive": 2,
  "foulsDrawn": 22,
  "foulsPersonal": 12,
  "foulsTeam": 10,
  "foulsTechnical": 0,
  "foulsTeamTechnical": 0,
  "freeThrowsAttempted": 26,
  "freeThrowsMade": 23,
  "freeThrowsPercentage": 0.8846153846153839,
  "leadChanges": 0,
  "minutes": "PT165M15.00S",
  "minutesCalculated": "PT165M",
  "points": 75,
  "pointsAgainst": 77,
  "pointsFastBreak": 7,
  "pointsFromTurnovers": 14,
  "pointsInThePaint": 28,
  "pointsInThePaintAttempted": 30,
  "pointsInThePaintMade": 14,
  "pointsInThePaintPercentage": 0.466666666666667,
  "pointsSecondChance": 14,
  "reboundsDefensive": 25,
  "reboundsOffensive": 12,
  "reboundsPersonal": 37,
  "reboundsTeam": 9,
  "reboundsTeamDefensive": 4,
  "reboundsTeamOffensive": 5,
  "reboundsTotal": 46,
  "secondChancePointsAttempted": 12,
  "secondChancePointsMade": 6,
  "secondChancePointsPercentage": 0.5,
  "steals": 3,
  "threePointersAttempted": 22,
  "threePointersMade": 6,
  "threePointersPercentage": 0.272727272727273,
  "timeLeading": "PT00M00.00S",
  "timesTied": 2,
  "trueShootingAttempts": 70.44,
  "trueShootingPercentage": 0.53236797274276,
  "turnovers": 14,
  "turnoversTeam": 0,
  "turnoversTotal": 14,
  "twoPointersAttempted": 37,
  "twoPointersMade": 17,
  "twoPointersPercentage": 0.45945945945946
}

Play by play

$pbp = new NBALive\NBAPlayByPlay('0022301214');

//Or set game id with
$pbp->game_id = "0022301214";

//Creates the arrays
$pbp->all_plays;
$pbp->plays_count;
$pbp->last_10_plays;

//Player only plays
$pbp->playerOnly(202331);

//Team only plays
$pbp->teamOnly(1610612746);

//Get a score line/worm
$pbp->scoreLine();

Play by play V3

$game_id = '0022300372';
$start_qtr = 1;
$end_qtr = 1;

$pbp_v3 = new NBALive\NBAPlayByPlayV3($game_id, $start_qtr, $end_qtr);

//Creates the arrays
$pbp_v3->all_plays;
$pbp_v3->plays_count;
$pbp_v3->last_10_plays;

//Player only plays
$pbp_v3->playerOnly(202331);

//Team only plays
$pbp_v3->teamOnly(1610612746);

//Scored only plays
$pbp_v3->scoredOnly();

//Get a score streaks for both teams
$pbp_v3->scoreStreaks();

Play by play V2

$game_id = '0022300372';
$start_qtr = 1;
$end_qtr = 1;

$pbp_v2 = new NBALive\NBAPlayByPlayV2($game_id, $start_qtr, $end_qtr);

//Creates the arrays
$pbp_v2->all_plays;
$pbp_v2->plays_count;
$pbp_v2->last_10_plays;

//Player only plays
$pbp_v2->playerOnly(202331);

//Team only plays
$pbp_v2->teamOnly(1610612746);

//Scored only plays
$pbp_v2->scoredOnly();

Play by play V1

$game_id = '0022300372';
$start_qtr = 1;
$end_qtr = 1;

$pbp_v1 = new NBALive\NBAPlayByPlayV1($game_id, $start_qtr, $end_qtr);

//Creates the arrays
$pbp_v1->all_plays;
$pbp_v1->plays_count;
$pbp_v1->last_10_plays;

//Scored only plays
$pbp_v1->scoredOnly();

Play by play clips

$game_id = '0022300372';
$event_number = 89;

$play_clip = new NBALive\NBAPlayByPlayClips($game_id, $event_number);

//Creates the arrays
$play_clip->media;
$play_clip->details;

Traditional box score

$bs = new NBALive\NBABoxScoreTraditional();
//Whole game
$bs->game_id = '0022300372';
$bs->fetch();

//Use true to only get home and visit players arrays and return early
$bs->fetch(true);

//Preset filter (Qtr 4)
$bs->game_id = '0022300372';
$bs->filter = $bs->buildQ4();//buildQ1(), buildQ2(), buildH1() etc.
$bs->fetch();

//Custom filter
$bs->game_id = '0022300372';
$bs->range_type = 1;
$bs->start_period = 4;
$bs->start_range = 0;
$bs->end_range = 28800;
$bs->end_period = 4;
$bs->filter = $bs->build();
$bs->fetch();

//Creates the arrays
$bs->teams;
$bs->teams_starters;
$bs->teams_bench;

$bs->home_team;
$bs->home_players;
$bs->home_starters;
$bs->home_bench;

$bs->away_team;
$bs->away_players;
$bs->away_starters;
$bs->away_bench;

$bs->sortAsc($bs->home_players, 'fieldGoalsAttempted');
$bs->sortDesc($bs->home_players, 'fieldGoalsMade');

Defensive box score

$defensive = new NBALive\NBABoxScoreDefensive("0022301203");

//Or set game id with
$defensive->game_id = "0022301203";

//Creates the arrays
$defensive->home_players;
$defensive->away_players;

Box score matchups

$matchups = new NBALive\NBABoxScoreMatchups("0022301203");

//Or set game id with
$matchups->game_id = "0022301203";

//Creates the arrays
$matchups->home_players;
$matchups->away_players;

//Get just a certain players matchups
$matchups->playerOnly(1629684);

//Get all matchups for a player
$matchups->playerMatchedWith(201935);

Scoring box score

$scoring = new NBALive\NBABoxScoreScoring();
//Whole game
$scoring->game_id = '0022300372';
$scoring->fetch();

//Preset filter (Qtr 4)
$scoring->game_id = '0022300372';
$scoring->filter = $bs->buildQ4();//buildQ1(), buildQ2(), buildH1() etc.
$scoring->fetch();

//Custom filter
$scoring->game_id = '0022300372';
$scoring->range_type = 1;
$scoring->start_period = 4;
$scoring->start_range = 0;
$scoring->end_range = 28800;
$scoring->end_period = 4;
$scoring->filter = $bs->build();
$scoring->fetch();

//Creates the arrays
$scoring->home_players;
$scoring->away_players;

$scoring->home_team;
$scoring->away_team;

Misc box score

$misc = new NBALive\NBABoxScoreMisc();
//Whole game
$misc->game_id = '0022300372';
$misc->fetch();

//Preset filter (Qtr 4)
$misc->game_id = '0022300372';
$misc->filter = $bs->buildQ4();//buildQ1(), buildQ2(), buildH1() etc.
$misc->fetch();

//Custom filter
$misc->game_id = '0022300372';
$misc->range_type = 1;
$misc->start_period = 4;
$misc->start_range = 0;
$misc->end_range = 28800;
$misc->end_period = 4;
$misc->filter = $bs->build();
$misc->fetch();

//Creates the arrays
$misc->home_players;
$misc->away_players;

$misc->home_team;
$misc->away_team;

Usage box score

$usage = new NBALive\NBABoxScoreUsage();
//Whole game
$usage->game_id = '0022300372';
$usage->fetch();

//Preset filter (Qtr 4)
$usage->game_id = '0022300372';
$usage->filter = $bs->buildQ4();//buildQ1(), buildQ2(), buildH1() etc.
$usage->fetch();

//Custom filter
$usage->game_id = '0022300372';
$usage->range_type = 1;
$usage->start_period = 4;
$usage->start_range = 0;
$usage->end_range = 28800;
$usage->end_period = 4;
$usage->filter = $bs->build();
$usage->fetch();

//Creates the arrays
$usage->home_players;
$usage->away_players;

$usage->home_team;
$usage->away_team;

4 factors box score

$fourfactors = new NBALive\NBABoxScore4Factors("0022301203");
//Whole game
$fourfactors->game_id = '0022300372';
$fourfactors->fetch();

//Preset filter (Qtr 4)
$fourfactors->game_id = '0022300372';
$fourfactors->filter = $bs->buildQ4();//buildQ1(), buildQ2(), buildH1() etc.
$fourfactors->fetch();

//Custom filter
$fourfactors->game_id = '0022300372';
$fourfactors->range_type = 1;
$fourfactors->start_period = 4;
$fourfactors->start_range = 0;
$fourfactors->end_range = 28800;
$fourfactors->end_period = 4;
$fourfactors->filter = $bs->build();
$fourfactors->fetch();

//Creates the arrays
$fourfactors->home_players;
$fourfactors->away_players;

$fourfactors->home_team;
$fourfactors->away_team;

Advanced box score

$adv = new NBALive\NBABoxScoreAdvanced();
//Whole game
$adv->game_id = '0022300372';
$adv->fetch();

//Preset filter (Qtr 4)
$adv->game_id = '0022300372';
$adv->filter = $bs->buildQ4();//buildQ1(), buildQ2(), buildH1() etc.
$adv->fetch();

//Custom filter
$adv->game_id = '0022300372';
$adv->range_type = 1;
$adv->start_period = 4;
$adv->start_range = 0;
$adv->end_range = 28800;
$adv->end_period = 4;
$adv->filter = $bs->build();
$adv->fetch();

//Creates the arrays
$adv->home_players;
$adv->away_players;

$adv->home_team;
$adv->away_team;

Tracking box score

$tracking = new NBALive\NBABoxScoreTracking();
//Whole game
$tracking->game_id = '0022300372';
$tracking->fetch();

//Preset filter (Qtr 4)
$tracking->game_id = '0022300372';
$tracking->filter = $bs->buildQ4();//buildQ1(), buildQ2(), buildH1() etc.
$tracking->fetch();

//Custom filter
$tracking->game_id = '0022300372';
$tracking->range_type = 1;
$tracking->start_period = 4;
$tracking->start_range = 0;
$tracking->end_range = 28800;
$tracking->end_period = 4;
$tracking->filter = $bs->build();
$tracking->fetch();

//Creates the arrays
$tracking->home_players;
$tracking->away_players;

$tracking->home_team;
$tracking->away_team;

Team lineups

$lineups = new NBALive\NBATeamLineups();

$lineups->team_id = 1610612746;
$lineups->season = '2019-20';//Optional if NOT set will just be current season
$lineups->players_amount = 5;
$lineups->fetch();

//Creates the array
$lineups->details;

//Get lineups that contain a certain player only
$lineups->playerOnly(202695)

Team Dash pts shots

$team_shots = new NBALive\NBATeamDashPtShots();

$team_shots->team_id = 1610612746;
$team_shots->season = '2019-20';//Optional if NOT set will just be current season
$team_shots->fetch();

//Creates the arrays
$team_shots->general_shooting;
$team_shots->shot_clock_shooting;
$team_shots->dribble_shooting;
$team_shots->closest_defender_shooting;
$team_shots->closest_defender_10ft_shooting;
$team_shots->touch_time_shooting;

Game rotations

$rotations = new NBALive\NBARotations("0022301203");

//Or set game id with
$rotations->game_id = "0022301203";

//Creates the array
$pbp->details;

//Player only rotation
$pbp->playerOnly(202331);

//Team only rotation
$pbp->teamOnly(1610612746);

Outputs

[
  {
    "team_id": 1610612756,
    "team_short": "Suns",
    "player_id": 201142,
    "player_name": "K.Durant",
    "in_period": 1,
    "in": "00:00",
    "in_time_left": "12:00",
    "out_period": 1,
    "out": "09:38",
    "out_time_left": "02:22",
    "total_time": "09:38",
    "pts": 4,
    "pts_diff": -4,
    "usg_pct": 0.174
  },
  {
    "team_id": 1610612756,
    "team_short": "Suns",
    "player_id": 201142,
    "player_name": "K.Durant",
    "in_period": 2,
    "in": "14:50",
    "in_time_left": "09:10",
    "out_period": 3,
    "out": "34:13",
    "out_time_left": "01:47",
    "total_time": "19:23",
    "pts": 17,
    "pts_diff": 12,
    "usg_pct": 0.304
  },
  {
    "team_id": 1610612756,
    "team_short": "Suns",
    "player_id": 201142,
    "player_name": "K.Durant",
    "in_period": 4,
    "in": "38:23",
    "in_time_left": "09:37",
    "out_period": 4,
    "out": "47:52",
    "out_time_left": "00:08",
    "total_time": "09:29",
    "pts": 10,
    "pts_diff": -2,
    "usg_pct": 0.278
  },
  {
    "team_id": 1610612756,
    "team_short": "Suns",
    "player_id": 201142,
    "player_name": "K.Durant",
    "in_period": 4,
    "in": "47:53",
    "in_time_left": "00:07",
    "out_period": 4,
    "out": "48:00",
    "out_time_left": "00:00",
    "total_time": "00:07",
    "pts": 0,
    "pts_diff": 0,
    "usg_pct": 0.5
  }
]

Team year over year

$team_yoy = new NBALive\NBATeamYearOverYear(1610612746);

//Creates the arrays
$team_yoy->details;
$team_yoy->latest;

Standings

use Corbpie\NBALive\NBAStandings;

// Auto-fetch via constructor
$standings = new NBAStandings('2025-26');

// Or fetch explicitly (re-fetches on demand)
$standings = new NBAStandings();
$standings->season = '2025-26';
$standings->fetch();

// Array access (backward compatible)
$standings->standings;
$standings->east_standings;
$standings->west_standings;

// Typed DTO access
foreach ($standings->standingEntries as $entry) {
    echo $entry->team . ': ' . $entry->wins . '-' . $entry->losses;
}

League game log

$gl = new NBALive\NBALeagueGameLog();

//Creates the array
$gl->games;

Team info

$team = new NBALive\NBATeamInfo(1610612746);

//Creates the arrays
$team->info;
$team->ranks;
$team->seasons;

Team game logs

use Corbpie\NBALive\NBATeamGameLogs;

$logs = new NBATeamGameLogs();
$logs->team_id = 1610612754;
$logs->season = '2025-26'; // Optional, defaults to CURRENT_SEASON
$logs->fetch();

// Array access (backward compatible)
$logs->games;
$logs->lastXGames(10); // Last 10 games

// Typed DTO access
foreach ($logs->gameLogs as $entry) {
    echo $entry->gameDate . ' ' . $entry->matchup . ' — ' . $entry->pts . ' pts';
}

Team franchise players

$players = new NBALive\NBAFranchisePlayers(1610612746);

//Creates the array
$players->players;

Schedule

$schedule = new NBALive\NBASchedule('2023-12-20');

//Creates the array
$schedule->schedule;

//Get full season schedule for a team
$schedule->fullForTeam(1610612746);

//Get tomorrow's games
$tomorrow = (new DateTimeImmutable('tomorrow', new DateTimeZone('America/New_York')))->format('Y-m-d');

$schedule = new NBALive\NBASchedule($tomorrow);

//Get upcoming games for a team in next 7 days
$schedule->upcomingGames(1610612746, 7);

Output

[
  {
    "game_id": "0022300364",
    "game_sequence": 1,
    "game_status": 1,
    "game_status_text": "7:00 pm ET",
    "game_code": "20231220\/UTACLE",
    "home_tid": 1610612739,
    "away_tid": 1610612762,
    "arena": "Rocket Mortgage FieldHouse",
    "live_period": null,
    "date_time_et": "2023-12-20 19:00:00",
    "date_time_utc": "2023-12-21 00:00:00"
  },
  {
    "game_id": "0022300365",
    "game_sequence": 2,
    "game_status": 1,
    "game_status_text": "7:00 pm ET",
    "game_code": "20231220\/CHAIND",
    "home_tid": 1610612754,
    "away_tid": 1610612766,
    "arena": "Gainbridge Fieldhouse",
    "live_period": null,
    "date_time_et": "2023-12-20 19:00:00",
    "date_time_utc": "2023-12-21 00:00:00"
  },
  {
    "game_id": "0022300366",
    "game_sequence": 3,
    "game_status": 1,
    "game_status_text": "7:00 pm ET",
    "game_code": "20231220\/MIAORL",
    "home_tid": 1610612753,
    "away_tid": 1610612748,
    "arena": "Amway Center",
    "live_period": null,
    "date_time_et": "2023-12-20 19:00:00",
    "date_time_utc": "2023-12-21 00:00:00"
  },
  {
    "game_id": "0022300367",
    "game_sequence": 4,
    "game_status": 1,
    "game_status_text": "7:00 pm ET",
    "game_code": "20231220\/MINPHI",
    "home_tid": 1610612755,
    "away_tid": 1610612750,
    "arena": "Wells Fargo Center",
    "live_period": null,
    "date_time_et": "2023-12-20 19:00:00",
    "date_time_utc": "2023-12-21 00:00:00"
  },
  {
    "game_id": "0022300368",
    "game_sequence": 5,
    "game_status": 1,
    "game_status_text": "7:30 pm ET",
    "game_code": "20231220\/NYKBKN",
    "home_tid": 1610612751,
    "away_tid": 1610612752,
    "arena": "Barclays Center",
    "live_period": null,
    "date_time_et": "2023-12-20 19:30:00",
    "date_time_utc": "2023-12-21 00:30:00"
  },
  {
    "game_id": "0022300369",
    "game_sequence": 6,
    "game_status": 1,
    "game_status_text": "7:30 pm ET",
    "game_code": "20231220\/DENTOR",
    "home_tid": 1610612761,
    "away_tid": 1610612743,
    "arena": "Scotiabank Arena",
    "live_period": null,
    "date_time_et": "2023-12-20 19:30:00",
    "date_time_utc": "2023-12-21 00:30:00"
  },
  {
    "game_id": "0022300370",
    "game_sequence": 7,
    "game_status": 1,
    "game_status_text": "8:00 pm ET",
    "game_code": "20231220\/LALCHI",
    "home_tid": 1610612741,
    "away_tid": 1610612747,
    "arena": "United Center",
    "live_period": null,
    "date_time_et": "2023-12-20 20:00:00",
    "date_time_utc": "2023-12-21 01:00:00"
  },
  {
    "game_id": "0022300371",
    "game_sequence": 8,
    "game_status": 1,
    "game_status_text": "8:00 pm ET",
    "game_code": "20231220\/ATLHOU",
    "home_tid": 1610612745,
    "away_tid": 1610612737,
    "arena": "Toyota Center",
    "live_period": null,
    "date_time_et": "2023-12-20 20:00:00",
    "date_time_utc": "2023-12-21 01:00:00"
  },
  {
    "game_id": "0022300372",
    "game_sequence": 9,
    "game_status": 1,
    "game_status_text": "8:30 pm ET",
    "game_code": "20231220\/LACDAL",
    "home_tid": 1610612742,
    "away_tid": 1610612746,
    "arena": "American Airlines Center",
    "live_period": null,
    "date_time_et": "2023-12-20 20:30:00",
    "date_time_utc": "2023-12-21 01:30:00"
  },
  {
    "game_id": "0022300373",
    "game_sequence": 10,
    "game_status": 1,
    "game_status_text": "10:00 pm ET",
    "game_code": "20231220\/BOSSAC",
    "home_tid": 1610612758,
    "away_tid": 1610612738,
    "arena": "Golden 1 Center",
    "live_period": null,
    "date_time_et": "2023-12-20 22:00:00",
    "date_time_utc": "2023-12-21 03:00:00"
  }
]

Hustle box score

$hustle = new NBALive\NBABoxScoreHustle("0022301203");

//Or set game id with
$hustle->game_id = "0022301203";

//Creates these arrays
$hustle->home_players;
$hustle->away_team;
$hustle->home_team;
$hustle->away_team;

Team array output

{
  "minutes": "240.000000:00",
  "points": 106,
  "contestedShots": 33,
  "contestedShots2pt": 21,
  "contestedShots3pt": 12,
  "deflections": 17,
  "chargesDrawn": 0,
  "screenAssists": 9,
  "screenAssistPoints": 20,
  "looseBallsRecoveredOffensive": 4,
  "looseBallsRecoveredDefensive": 0,
  "looseBallsRecoveredTotal": 4,
  "offensiveBoxOuts": 2,
  "defensiveBoxOuts": 3,
  "boxOutPlayerTeamRebounds": 5,
  "boxOutPlayerRebounds": 4,
  "boxOuts": 5
}

Game summary

$sum = new NBALive\NBAGameSummary("0022301203");

//Or set game id with
$sum->game_id = "0022301203";

//Creates these arrays
$sum->home;
$sum->away;
$sum->refs;
$sum->inactive;
$sum->home_line_score;
$sum->away_line_score;
$sum->last_meeting;
$sum->statuses;

//Int
$sum->attendance;

Output for $sum->away

{
  "team_id": 1610612756,
  "team_name_short": "PHX",
  "pts_paint": 42,
  "pts_second_chance": 10,
  "pts_fast_break": 27,
  "largest_lead": 3,
  "lead_changes": 14,
  "times_tied": 11,
  "team_turnovers": 2,
  "total_turnovers": 22,
  "team_rebounds": 11,
  "pts_off_to": 25
}

Team roster

$roster = new NBALive\NBARosters(1610612754, '2014-15');

//Creates the array
$roster->players;
$roster->coaches;

League leaders

$stat = 'PTS';
$mode = 'Totals'
$season = '2023-24'
$type = 'Regular+Season'

$ll = new NBALive\NBALeagueLeaders($stat, $mode, $season, $type);

//Creates the array
$ll->details;

Player year over year

$yoy = new NBALive\NBAPlayerYearOverYear();
$yoy->player_id = 202331;//Required
$yoy->per_mode = 'PerGame';
//Set this if you want to get a specific season:
$yoy->season = '2019-20';

//Must run fetch()
$yoy->fetch();

//Creates the arrays
$yoy->details;
//For the specific season
$yoy->season_array;

Player on off

$on_off = new NBALive\NBATeamPlayerOnOff();
$on_off->team_id = 1610612746;
$on_off->season = '2023-24';

//Must run fetch()
$yoy->fetch();

//Creates the arrays
$yoy->on;
$yoy->off;

//Get a specific player on and off
$on_off->player(201587);

//This build and returns:
$on_off->player_only;

Output for $on_off->player_only

{
  "on": {
    "player_id": 202331,
    "player": "George, Paul",
    "team_id": 1610612746,
    "team": "LAC",
    "season": "2023-24",
    "season_type": "Regular Season",
    "per_mode": "Totals",
    "status": "ON",
    "gp": 26,
    "w": 15,
    "l": 11,
    "w_pct": 0.577,
    "min": 899.96,
    "fgm": 826,
    "fga": 1638,
    "fg_pct": 0.504,
    "fg3m": 244,
    "fg3a": 591,
    "fg3_pct": 0.413,
    "ftm": 353,
    "fta": 443,
    "ft_pct": 0.797,
    "oreb": 179,
    "dreb": 635,
    "reb": 814,
    "ast": 504,
    "pf": 363,
    "pfd": 393,
    "stl": 162,
    "tov": 236,
    "blk": 95,
    "blka": 85,
    "pts": 2249,
    "plus_minus": 184,
    "gp_rank": 5,
    "w_rank": 5,
    "l_rank": 18,
    "w_pct_rank": 17,
    "min_rank": 2,
    "fgm_rank": 2,
    "fga_rank": 2,
    "fg_pct_rank": 2,
    "fg3m_rank": 1,
    "fg3a_rank": 2,
    "fg3_pct_rank": 5,
    "ftm_rank": 2,
    "fta_rank": 2,
    "ft_pct_rank": 9,
    "oreb_rank": 2,
    "dreb_rank": 2,
    "reb_rank": 2,
    "ast_rank": 2,
    "pf_rank": 21,
    "pfd_rank": 2,
    "stl_rank": 2,
    "tov_rank": 20,
    "blk_rank": 2,
    "blka_rank": 21,
    "pts_rank": 2,
    "plus_minus_rank": 2
  },
  "off": {
    "player_id": 202331,
    "player": "George, Paul",
    "team_id": 1610612746,
    "team": "LAC",
    "season": "2023-24",
    "season_type": "Regular Season",
    "per_mode": "Totals",
    "status": "OFF",
    "gp": 28,
    "w": 17,
    "l": 11,
    "w_pct": 0.607,
    "min": 449.04,
    "fgm": 370,
    "fga": 822,
    "fg_pct": 0.45,
    "fg3m": 107,
    "fg3a": 327,
    "fg3_pct": 0.327,
    "ftm": 180,
    "fta": 223,
    "ft_pct": 0.807,
    "oreb": 118,
    "dreb": 299,
    "reb": 417,
    "ast": 207,
    "pf": 202,
    "pfd": 175,
    "stl": 72,
    "tov": 135,
    "blk": 55,
    "blka": 46,
    "pts": 1027,
    "plus_minus": -30,
    "gp_rank": 1,
    "w_rank": 1,
    "l_rank": 9,
    "w_pct_rank": 7,
    "min_rank": 16,
    "fgm_rank": 16,
    "fga_rank": 16,
    "fg_pct_rank": 22,
    "fg3m_rank": 17,
    "fg3a_rank": 16,
    "fg3_pct_rank": 22,
    "ftm_rank": 16,
    "fta_rank": 16,
    "ft_pct_rank": 5,
    "oreb_rank": 16,
    "dreb_rank": 16,
    "reb_rank": 16,
    "ast_rank": 16,
    "pf_rank": 7,
    "pfd_rank": 16,
    "stl_rank": 16,
    "tov_rank": 7,
    "blk_rank": 16,
    "blka_rank": 5,
    "pts_rank": 16,
    "plus_minus_rank": 21
  }
}

Player shooting

$player = new NBALive\NBAPlayerShooting();

//Or set player id with
$player->player_id = 202331;
$player->season = '2019-20';

//Creates the arrays
$player->shot_5ft = [];
$player->shot_8ft = [];
$player->shot_area = [];
$player->assisted = [];
$player->shot_types_summary = [];
$player->shot_types = [];
$player->assisted_by = [];

Player data

$player = new NBALive\NBAPlayer(202331);

//Or set player id with
$player->player_id = 202331;

//Creates the arrays
$player->details;
$player->seasons;

Details:

{
  "id": 202331,
  "first_name": "Paul",
  "last_name": "George",
  "short_name": "P. George",
  "slug": "paul-george",
  "birthdate": "1990-05-02",
  "age": 33,
  "school": "Fresno State",
  "last_aff": "Fresno State\/USA",
  "country": "USA",
  "height": "6-8",
  "height_cm": 203,
  "weight": 220,
  "weight_kg": 100,
  "seasons": 13,
  "jersey": 13,
  "position": "Forward",
  "status": "Active",
  "current_team_id": 1610612746,
  "current_team_name": "Clippers",
  "current_team_short": "LAC",
  "from_year": 2010,
  "to_year": 2023,
  "draft_year": 2010,
  "draft_round": 1,
  "draft_number": 10,
  "played_current_season": true
}

Player awards

$awards = new NBALive\NBAPlayerAwards(202331);

//Creates the array
$player->awards;

Player career

$awards = new NBALive\NBAPlayerCareer(202331, 'Totals');

//Creates the arrays
$player->season_totals_regular;
$player->career_totals_regular;
$player->season_totals_post;
$player->career_totals_post;
$player->season_totals_all_star;
$player->career_totals_all_star;
$player->season_totals_college;
$player->career_totals_college;
$player->season_totals_showcase;
$player->career_totals_showcase;
$player->season_rankings_regular;
$player->season_rankings_post;

Playoff brackets

$series = new NBALive\NBAPlayoffBracket('2023');

$all = $series->results;
$east = $series->east;
$west = $series->west;

$in_progress = $series->in_progress;
$completed = $series->completed;

Playoff picture

$playoffs = new NBALive\NBAPlayoffPicture('22023');

Playoff series

$playoff_series = new NBALive\NBAPlayoffSeries('2023-24');

Team

$team = new NBALive\NBATeam(1610612757);


//Or set team id with
$team->team_id = 1610612757;

//Creates the array
$team->details;

Teams years

$teams = new NBALive\NBATeamYears();

//Creates the array
$teams->teams;

Outputs

{
  "id": 1610612757,
  "name": "Trail Blazers",
  "short_name": "POR",
  "city": "Portland",
  "arena": "Moda Center",
  "year_founded": 1970
}

League player match ups

$match_ups = new NBALive\NBAMatchups();
$match_ups->season = '2023-24';

//Get only players from a team with
$match_ups->off_team_id = 1610612757;

//Get only certain player
$match_ups->off_player_id = 202331;

//Call fetch
$match_ups->fetch();

//Creates the array
$match_ups->details;

League player shot locations

$shots = new NBALive\NBALeaguePlayerShotLocations();
$shots->season = '2023-24';

//Get only players from a team with
$shots->team_id = 1610612757;

//Choose location/range type
$shots->distance_range = 'By Zone';
$shots->distance_range = '5ft Range';
$shots->distance_range = '8ft Range';

//Creates the arrays depending on distance_range
$shots->zone;
$shots->range_5ft;
$shots->range_8ft;

League player shots

$shots = new NBALive\NBALeaguePlayerShotPts();
$shots->season = '2023-24';

//Get only players from a team with
$shots->team_id = 1610612757;

//Creates the array
$shots->details;

Video events

$ve = new NBALive\NBAVideoEvents(1, '0022300568');

//Creates the array
$ve->details;

Player game logs

$logs = new NBALive\NBAPlayerGameLogs();
$logs->player_id = 202331;
$logs->season = '2023-24'; // Optional
$logs->fetch();

//Creates the array
$logs->games;

//Get last X games
$logs->lastXGames(10);

Player compare

// Compare two players head-to-head
$compare = new NBALive\NBAPlayerCompare(202331, 201566, '2023-24', 'PerGame');

//Creates the arrays
$compare->player1;
$compare->player2;
$compare->overall;

Player next games

// Get upcoming games for a player
$next = new NBALive\NBAPlayerNextGames(202331, 5, '2024-25');

//Creates the array
$next->games;

Player vs player

// Head-to-head matchup stats
$vs = new NBALive\NBAPlayerVsPlayer(202331, 201566, '2023-24', 'PerGame');

//Creates the arrays
$vs->player1_overall;
$vs->player2_overall;
$vs->player1_on_court;
$vs->player2_on_court;

Player index

$index = new NBALive\NBAPlayerIndex();
$index->season = '2024-25';
$index->team_id = 1610612746; // Optional filter
$index->country = 'USA'; // Optional filter
$index->college = 'Duke'; // Optional filter
$index->fetch();

//Creates the array
$index->players;

//Search by name
$results = $index->searchByName('LeBron');

Shot chart

// Get shot chart data with coordinates
$shots = new NBALive\NBAShotChart(202331, 0, '2023-24');

//Creates the arrays
$shots->shots;
$shots->made_shots;
$shots->missed_shots;
$shots->league_averages;

//Filter by zone
$restricted = $shots->byZone('Restricted Area');

//Get shooting percentage
$pct = $shots->getShootingPct();

Draft history

// Get draft history (filter by year, team, or college)
$draft = new NBALive\NBADraftHistory('2023', null, null);

//Creates the array
$draft->picks;

//Filter by round
$firstRound = $draft->byRound(1);

//Get lottery picks only
$lottery = $draft->lotteryPicks();

Draft combine

// Get draft combine measurements
$combine = new NBALive\NBADraftCombine('2024-25');

//Creates the array
$combine->players;

//Sort by measurement
$tallest = $combine->sortBy('height_w_shoes', 'desc');
$fastest = $combine->sortBy('three_quarter_sprint', 'asc');

Franchise history

$history = new NBALive\NBAFranchiseHistory();

//Creates the arrays
$history->active;
$history->defunct;

//Get specific franchise
$lakers = $history->getByTeamId(1610612747);

Franchise leaders

// Get all-time franchise leaders
$leaders = new NBALive\NBAFranchiseLeaders(1610612746);

//Creates the array
$leaders->leaders;

All-time leaders

// Get NBA all-time leaders for a stat category
$allTime = new NBALive\NBAAllTimeLeaders('PTS', 'Totals', 10);

//Creates the array
$allTime->leaders;

// Available categories: GP, PTS, AST, REB, STL, BLK, FGM, FGA, FG_PCT, 
// FG3M, FG3A, FG3_PCT, FTM, FTA, FT_PCT, OREB, DREB, TOV, PF

Team historical leaders

$teamLeaders = new NBALive\NBATeamHistoricalLeaders(1610612746);

//Creates the arrays
$teamLeaders->career_leaders;
$teamLeaders->season_leaders;

Team dashboard

$dashboard = new NBALive\NBATeamDashboard();
$dashboard->team_id = 1610612746;
$dashboard->season = '2023-24';
$dashboard->fetch();

//Creates the arrays
$dashboard->overall;
$dashboard->by_location; // Home vs Away
$dashboard->by_outcome;  // Wins vs Losses
$dashboard->by_month;
$dashboard->by_season_segment; // Pre/Post All-Star

Win probability

// Get win probability data for a game
$wp = new NBALive\NBAWinProbability('0022300372');

//Creates the array
$wp->probabilities;

//Get biggest swings in win probability
$swings = $wp->biggestSwings(10);

//Get probability at end of each quarter
$quarters = $wp->byQuarterEnd();

Player clutch stats

// League-wide clutch time stats (last 5 min, within 5 pts)
$clutch = new NBALive\NBALeagueDashPlayerClutch();
$clutch->season = '2023-24';
$clutch->fetch();

//Creates the array
$clutch->players;

//Get top clutch performers
$topClutch = $clutch->topPerformers('pts', 10);

Team clutch stats

$teamClutch = new NBALive\NBALeagueDashTeamClutch();
$teamClutch->season = '2023-24';
$teamClutch->fetch();

//Creates the array
$teamClutch->teams;

//Get best clutch teams
$best = $teamClutch->bestClutchTeams(10);

League hustle stats

$hustle = new NBALive\NBALeagueHustleStats();
$hustle->season = '2023-24';
$hustle->fetch();

//Creates the array
$hustle->players;

//Get top hustlers by stat
$deflectors = $hustle->topHustlers('deflections', 10);
$chargers = $hustle->topHustlers('charges_drawn', 10);

League game finder

use Corbpie\NBALive\NBALeagueGameFinder;

$finder = new NBALeagueGameFinder();
$finder->season = '2025-26';
$finder->team_id = 1610612754;   // Optional
$finder->date_from = '2025-01-01'; // Optional
$finder->date_to = '2025-01-31';   // Optional
$finder->outcome = 'W';            // Optional (W or L)
$finder->fetch();

// Array access (backward compatible)
$finder->games;
$finder->highScoringGames(120);

// Typed DTO access
foreach ($finder->gameEntries as $game) {
    echo $game->matchup . ': ' . $game->pts . ' pts';
}

Player fantasy profile

$fantasy = new NBALive\NBAPlayerFantasyProfile();
$fantasy->player_id = 202331;
$fantasy->season = '2023-24';
$fantasy->fetch();

//Creates the arrays
$fantasy->overall;
$fantasy->last_n_games;
$fantasy->by_opponent;

Team game streak finder

$streaks = new NBALive\NBATeamGameStreakFinder();
$streaks->team_id = 1610612746;
$streaks->season = '2023-24';
$streaks->min_games = 3;
$streaks->streak_type = 'W'; // W for wins, L for losses
$streaks->fetch();

//Creates the array
$streaks->streaks;

//Get longest streak
$longest = $streaks->longestStreak();

Player estimated metrics

$metrics = new NBALive\NBAPlayerEstimatedMetrics();
$metrics->season = '2023-24';
$metrics->fetch();

//Creates the array
$metrics->players;

//Get top players by net rating
$topNet = $metrics->topByNetRating(10);

//Get best offensive players
$topOff = $metrics->topOffensive(10);

//Get best defensive players
$topDef = $metrics->topDefensive(10);

corbpie / nbalive

Maintainers

Package info

Statistics

Security

README

Table of contents / index

Installing

Requirements

How it works

Fetching data

Error handling

Debugging

Custom HTTP client

Response caching

Typed DTOs

Custom HTTP client

Explicit fetch()

Helpers

Testing & development

Todays games and live

Game time seconds formatted (Helper function)

Boxscore

Play by play

Play by play V3

Play by play V2

Play by play V1

Play by play clips

Traditional box score

Defensive box score

Box score matchups

Scoring box score

Misc box score

Usage box score

4 factors box score

Advanced box score

Tracking box score

Team lineups

Team Dash pts shots

Game rotations

Team year over year

Standings

League game log

Team info

Team game logs

Team franchise players

Schedule

Hustle box score

Game summary

Team roster

League leaders

Player year over year

Player on off

Player shooting

Player data

Player awards

Player career

Playoff brackets

Playoff picture

Playoff series

Team

Teams years

League player match ups

League player shot locations

League player shots

Video events

Player game logs

Player compare

Player next games

Player vs player

Player index

Shot chart

Draft history

Draft combine

Franchise history

Franchise leaders

All-time leaders

Team historical leaders

Team dashboard

Win probability