PHPackages                             izaghar/xivapi-php - 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. izaghar/xivapi-php

ActiveLibrary[API Development](/categories/api)

izaghar/xivapi-php
==================

PHP client for XIVAPI v2

v2.2.0(5mo ago)02821MITPHPPHP ^8.3CI passing

Since Dec 8Pushed 5mo agoCompare

[ Source](https://github.com/izaghar/xivapi-php)[ Packagist](https://packagist.org/packages/izaghar/xivapi-php)[ Docs](https://github.com/izaghar/xivapi-php)[ RSS](/packages/izaghar-xivapi-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (5)Versions (5)Used By (1)

XIVAPI PHP Client
=================

[](#xivapi-php-client)

A modern PHP client for [XIVAPI v2](https://v2.xivapi.com) — the Final Fantasy XIV game data API.

[![PHP 8.3+](https://camo.githubusercontent.com/89899a77bdce65fc4c3d3423dfacff9c6461066a0b5354dc18d7721c23ba596e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d626c75652e737667)](https://www.php.net/)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![codecov](https://camo.githubusercontent.com/39856bca0bae8414dc8e13134e6959da1da13f3d8995af5ff9362e168696d937/68747470733a2f2f636f6465636f762e696f2f67682f697a61676861722f7869766170692d7068702f67726170682f62616467652e7376673f746f6b656e3d534b3847434c3746394a)](https://codecov.io/gh/izaghar/xivapi-php)

---

Table of Contents
-----------------

[](#table-of-contents)

- [Introduction](#introduction)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Global Configuration](#global-configuration)
- [API Reference](#api-reference)
    - [Game Versions](#game-versions)
    - [Sheet Index](#sheet-index)
    - [Sheet Rows](#sheet-rows)
    - [Single Row](#single-row)
    - [Search](#search)
    - [Assets](#assets)
    - [Map Assets](#map-assets)
- [Query Builders](#query-builders)
    - [Field Builder](#field-builder)
    - [SearchQuery Builder](#searchquery-builder)
- [Response Classes](#response-classes)
- [Error Handling](#error-handling)
- [Debugging](#debugging)
- [Enums Reference](#enums-reference)
- [Examples](#examples)
- [License](#license)

---

Introduction
------------

[](#introduction)

XIVAPI provides access to Final Fantasy XIV game data including items, actions, quests, and more. This library offers a clean, fluent PHP interface for the XIVAPI v2 endpoints.

**Features:**

- Full coverage of all XIVAPI v2 endpoints
- Fluent query builders for fields and search queries
- PSR-18 HTTP client compatibility (use any HTTP client you prefer)
- Strong typing with PHP 8.3 enums
- Global configuration for language, version, and schema

For the official API documentation, visit [v2.xivapi.com/docs](https://v2.xivapi.com/docs).

---

Requirements
------------

[](#requirements)

- **PHP 8.3** or higher
- A **PSR-18 HTTP client** (e.g., Guzzle, Symfony HttpClient)
- A **PSR-17 HTTP factory** (usually bundled with the HTTP client)

---

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

[](#installation)

Install via Composer:

```
composer require izaghar/xivapi-php
```

You also need a PSR-18 compatible HTTP client. Here are some options:

**With Guzzle:**

```
composer require guzzlehttp/guzzle
```

**With Symfony HttpClient:**

```
composer require symfony/http-client nyholm/psr7
```

---

Quick Start
-----------

[](#quick-start)

```
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use XivApi\XivApi;
use XivApi\Enums\Language;

// Create the API client
$api = new XivApi(
    new Client(),
    new HttpFactory()
);

// Fetch an item
$item = $api->sheet('Item')->row(4)->get();
echo $item->fields['Name']; // "Wind Shard"

// Search for items
$results = $api->search()
    ->query('Name~"Potion"')
    ->sheets(['Item'])
    ->get();

foreach ($results->results as $result) {
    echo $result->fields['Name'] . "\n";
}
```

---

Global Configuration
--------------------

[](#global-configuration)

Configure default settings that apply to all requests:

```
use XivApi\Enums\Language;

$api = (new XivApi($http, $factory))
    ->language(Language::German)           // Default language for all requests
    ->gameVersion('7.0')                   // Lock to a specific game version
    ->schema('exdschema@latest')           // Use a specific schema
    ->localizations(Language::English, Language::Japanese); // For field expansion
```

All settings are optional and can be overridden per-request.

### Configuration Methods

[](#configuration-methods)

MethodDescription`language(Language $lang)`Set the default language for text fields`gameVersion(string $version)`Lock requests to a specific game version`schema(string $schema)`Use a specific schema for field definitions`localizations(Language ...$langs)`Languages used when expanding localized fields---

API Reference
-------------

[](#api-reference)

### Game Versions

[](#game-versions)

List all available game versions.

```
$response = $api->version()->get();

foreach ($response->versions as $version) {
    echo $version->key . ': ' . implode(', ', $version->names) . "\n";
}
// Output: "2139246928a48a9a: 7.01, latest"
```

**Endpoint:** `GET /version`

---

### Sheet Index

[](#sheet-index)

List all available sheets (Excel files containing game data).

```
$response = $api->sheetIndex()->list();

foreach ($response->sheets as $sheetName) {
    echo $sheetName . "\n";
}
// Output: "Action", "Item", "Quest", ...
```

**Endpoint:** `GET /sheet`

**Available Methods:**

MethodDescription`version(string $v)`Use a specific game version`list()`Execute and return `SheetListResponse``getUrl()`Get the request URL (for debugging)---

### Sheet Rows

[](#sheet-rows)

Query multiple rows from a sheet.

```
// Basic query
$items = $api->sheet('Item')
    ->fields('Name,Icon,Description')
    ->language(Language::English)
    ->limit(50)
    ->get();

foreach ($items->rows as $row) {
    echo $row->rowId . ': ' . $row->fields['Name'] . "\n";
}
```

**Endpoint:** `GET /sheet/{sheet}`

**Available Methods:**

MethodDescription`fields(string|Field|array $fields)`Select specific fields`transient(string|Field|array $fields)`Select fields from transient sheet`language(Language $lang)`Set the language`schema(string $schema)`Use a specific schema`version(string $v)`Use a specific game version`limit(int $n)`Limit number of rows returned`after(string|int $rowId)`Pagination: fetch rows after this ID`rows(array $ids)`Fetch specific row IDs`get()`Execute and return `SheetResponse``getUrl()`Get the request URL (for debugging)#### Pagination

[](#pagination)

```
// First page
$page1 = $api->sheet('Item')->limit(100)->get();

// Next page (using the last row ID)
$lastRowId = end($page1->rows)->rowId;
$page2 = $api->sheet('Item')->limit(100)->after($lastRowId)->get();
```

#### Fetch Specific Rows

[](#fetch-specific-rows)

```
$items = $api->sheet('Item')
    ->rows([1, 2, 3, 4, 5])
    ->get();
```

---

### Single Row

[](#single-row)

Fetch a single row by ID.

```
$item = $api->sheet('Item')->row(4)->get();

echo $item->rowId;           // 4
echo $item->fields['Name'];  // "Wind Shard"
echo $item->version;         // "2139246928a48a9a"
echo $item->schema;          // "exdschema@..."
```

**Endpoint:** `GET /sheet/{sheet}/{row}`

**Available Methods:**

MethodDescription`fields(string|Field|array $fields)`Select specific fields`transient(string|Field|array $fields)`Select fields from transient sheet`language(Language $lang)`Set the language`schema(string $schema)`Use a specific schema`version(string $v)`Use a specific game version`get()`Execute and return `RowResponse``getUrl()`Get the request URL (for debugging)#### Subrows

[](#subrows)

Some sheets have subrows (e.g., `262144:0`, `262144:1`). Access them with a string:

```
$row = $api->sheet('GilShopItem')->row('262144:1')->get();

echo $row->rowId;    // 262144
echo $row->subrowId; // 1
```

---

### Search

[](#search)

Search across one or more sheets using a query string.

```
$results = $api->search()
    ->query('Name~"Potion" +Level>=1')
    ->sheets(['Item'])
    ->fields('Name,Icon,LevelItem')
    ->limit(20)
    ->get();

foreach ($results->results as $result) {
    echo sprintf(
        "[%s] %s #%d: %s (score: %.2f)\n",
        $result->sheet,
        $result->rowId,
        $result->fields['Name'],
        $result->score
    );
}
```

**Endpoint:** `GET /search`

**Available Methods:**

MethodDescription`query(string|SearchQuery $q)`The search query`sheets(array $sheets)`Sheets to search in`fields(string|Field|array $fields)`Select specific fields`transient(string|Field|array $fields)`Select fields from transient sheet`language(Language $lang)`Set the language`schema(string $schema)`Use a specific schema`version(string $v)`Use a specific game version`limit(int $n)`Limit number of results`cursor(string $cursor)`Continue from a previous search`get()`Execute and return `SearchResponse``getUrl()`Get the request URL (for debugging)#### Search Query Syntax

[](#search-query-syntax)

```
// Partial string match (contains)
'Name~"Potion"'

// Exact equality
'LevelItem=50'

// Numeric comparisons
'LevelItem>=50'
'LevelItem=1'
```

#### Cursor Pagination

[](#cursor-pagination)

```
$page1 = $api->search()
    ->query('Name~"Potion"')
    ->sheets(['Item'])
    ->limit(20)
    ->get();

if ($page1->hasMore()) {
    $page2 = $api->search()
        ->cursor($page1->next)
        ->get();
}
```

---

### Assets

[](#assets)

Fetch game assets (icons, textures) in various formats.

```
// Get PNG image data
$imageData = $api->asset('ui/icon/051000/051474_hr1.tex')->get();
file_put_contents('icon.png', $imageData);

// Different format
use XivApi\Enums\AssetFormat;

$jpg = $api->asset('ui/loadingimage/title/ffxiv_logo_jpen.tex', AssetFormat::Jpg)->get();
```

**Endpoint:** `GET /asset`

**Available Methods:**

MethodDescription`version(string $v)`Use a specific game version`get()`Execute and return binary image data`fetch()`Execute and return full PSR-7 Response`getUrl()`Get the request URL (for debugging)#### Using the PSR-7 Response

[](#using-the-psr-7-response)

```
$response = $api->asset('ui/icon/051000/051474_hr1.tex')->fetch();

$etag = $response->getHeaderLine('ETag');
$contentType = $response->getHeaderLine('Content-Type');
$body = $response->getBody()->getContents();
```

---

### Map Assets

[](#map-assets)

Fetch composed map images.

```
// Get a map image (JPEG)
$mapData = $api->map('s1d1', '00')->get();
file_put_contents('map.jpg', $mapData);
```

**Endpoint:** `GET /asset/map/{territory}/{index}`

**Parameters:**

- `territory` — Territory ID (e.g., `s1d1`, `r1f1`)
- `index` — Map index, zero-padded (e.g., `00`, `01`)

**Available Methods:**

MethodDescription`version(string $v)`Use a specific game version`get()`Execute and return binary image data`fetch()`Execute and return full PSR-7 Response`getUrl()`Get the request URL (for debugging)---

Query Builders
--------------

[](#query-builders)

### Field Builder

[](#field-builder)

For complex field selections, use the `Field` class:

```
use XivApi\Query\Field;
use XivApi\Enums\Language;
use XivApi\Enums\Transform;

$api->sheet('Item')
    ->fields([
        Field::make('Name'),
        Field::make('Description')->as(Transform::Html),
        Field::make('ItemUICategory.Name'),
    ])
    ->get();
```

#### Field Methods

[](#field-methods)

MethodDescriptionExample Output`make(string $name)`Create a field`Name``lang(Language $l)`Set explicit language`Name@lang(de)``as(Transform $t)`Apply transformation`Description@as(html)``asRaw()`Apply raw transformation`Icon@as(raw)``asHtml()`Apply HTML transformation`Description@as(html)``localized(Language ...$l)`Expand to multiple languages`Name,Name@lang(de),Name@lang(fr)`#### Localized Fields

[](#localized-fields)

Get a field in multiple languages at once:

```
// Explicit languages
Field::make('Name')->localized(Language::German, Language::French)
// Builds: Name,Name@lang(de),Name@lang(fr)

// Use globally configured languages
$api = (new XivApi($http, $factory))
    ->localizations(Language::German, Language::French);

$api->sheet('Item')
    ->fields([
        Field::make('Name')->localized(), // Uses global languages
        Field::make('Icon'),              // Not localized
    ])
    ->get();
```

#### Transformations

[](#transformations)

```
// HTML formatting for strings with markup
Field::make('Description')->as(Transform::Html)
// Or using the shortcut:
Field::make('Description')->asHtml()

// Raw value (skip relation resolution)
Field::make('ItemUICategory')->as(Transform::Raw)
// Or using the shortcut:
Field::make('ItemUICategory')->asRaw()
```

#### Nested Fields

[](#nested-fields)

Use dot-notation for nested fields:

```
Field::make('ItemUICategory.Name')
Field::make('ItemUICategory.Name')->lang(Language::Japanese)
```

---

### SearchQuery Builder

[](#searchquery-builder)

Build search queries programmatically instead of writing raw query strings:

```
use XivApi\Query\SearchQuery;
use XivApi\Enums\Language;

// Simple conditions
$query = SearchQuery::where('LevelItem', 50);
$query = SearchQuery::where('Name')->contains('Potion');

// Shortcuts
$query = SearchQuery::where('Name', 'Potion')       // equals
    ->where('Level', '>=', 90);                     // greaterOrEqual

// Chained conditions
$query = SearchQuery::where('Name')->contains('Potion')
    ->where('LevelItem')->greaterOrEqual(10)
    ->whereNot('Name')->contains('Hi-');

// Pass to search
$api->search()
    ->query($query)
    ->sheets(['Item'])
    ->get();
```

> **Note:** You can also use `SearchQuery::make()` to create an empty instance first.

#### Condition Methods

[](#condition-methods)

MethodPrefixDescription`where($field)``+`Must match`whereNot($field)``-`Must not match`orWhere($field)`(none)OR / optional#### Shortcuts

[](#shortcuts)

```
->where('Field', $value)              // equals
->where('Field', '=', $value)         // equals
->where('Field', '~', $value)         // contains
->where('Field', '>', $value)         // greaterThan
->where('Field', '=', $value)        // greaterOrEqual
->where('Field', '', 0)
    ->orWhere('Name')->localizedTo(Language::Japanese)->contains('ドラゴン')
    ->whereGroup(fn($q) => $q
        ->orWhere('Level', 80)
        ->orWhere('Level', 90)
    );
// Builds: +IsFlying=true +ExtraSeats>0 Name@ja~"ドラゴン" +(Level=80 Level=90)
```

---

Response Classes
----------------

[](#response-classes)

ClassReturned ByKey Properties`VersionsResponse``version()->get()``versions[]``Version`—`key`, `names[]``SheetListResponse``sheetIndex()->list()``sheets[]``SheetResponse``sheet()->get()``rows[]`, `version`, `schema``RowResponse``sheet()->row()->get()``rowId`, `subrowId`, `fields`, `transient`, `version`, `schema``Row`—`rowId`, `subrowId`, `fields`, `transient``SearchResponse``search()->get()``results[]`, `next`, `version`, `schema``SearchResult`—`sheet`, `rowId`, `subrowId`, `score`, `fields`, `transient`### Checking for More Results

[](#checking-for-more-results)

```
$response = $api->search()->query('...')->sheets(['Item'])->get();

if ($response->hasMore()) {
    // Use $response->next as cursor for next page
}
```

---

Error Handling
--------------

[](#error-handling)

All API errors throw `XivApiException`:

```
use XivApi\Exception\XivApiException;

try {
    $api->sheet('InvalidSheet')->get();
} catch (XivApiException $e) {
    echo $e->getMessage();   // Error message from API
    echo $e->statusCode;     // HTTP status code (e.g., 404)
}
```

---

Debugging
---------

[](#debugging)

Every client has a `getUrl()` method to inspect the request URL:

```
$url = $api->sheet('Item')
    ->fields('Name,Icon')
    ->language(Language::German)
    ->limit(10)
    ->getUrl();

echo $url;
// https://v2.xivapi.com/api/sheet/Item?fields=Name,Icon&language=de&limit=10
```

---

Enums Reference
---------------

[](#enums-reference)

### Language

[](#language)

```
use XivApi\Enums\Language;

Language::Japanese  // ja
Language::English   // en
Language::German    // de
Language::French    // fr
```

### Transform

[](#transform)

```
use XivApi\Enums\Transform;

Transform::Raw   // Skip relation resolution
Transform::Html  // Format string as HTML
```

### AssetFormat

[](#assetformat)

```
use XivApi\Enums\AssetFormat;

AssetFormat::Png   // PNG image (default)
AssetFormat::Jpg   // JPEG image
AssetFormat::Webp  // WebP image
```

---

Examples
--------

[](#examples)

See the [examples/Readme.md](examples/README.md) for runnable code samples:

- **Versions** — List game versions
- **Sheets** — Query sheet data with pagination
- **Search** — Various search patterns
- **Assets** — Download icons and maps

---

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance72

Regular maintenance activity

Popularity11

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~1 days

Total

4

Last Release

157d ago

Major Versions

v1.0.0 → v2.0.02025-12-09

### Community

Maintainers

![](https://www.gravatar.com/avatar/8ca99c235fec2611f26dd07b6889a6dc6bdbc4ef5c4d81c69aa3429dab16775d?d=identicon)[izaghar](/maintainers/izaghar)

---

Top Contributors

[![izaghar](https://avatars.githubusercontent.com/u/246080545?v=4)](https://github.com/izaghar "izaghar (7 commits)")

---

Tags

api clientffxivxivapifinal-fantasy

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/izaghar-xivapi-php/health.svg)

```
[![Health](https://phpackages.com/badges/izaghar-xivapi-php/health.svg)](https://phpackages.com/packages/izaghar-xivapi-php)
```

###  Alternatives

[kbsali/redmine-api

Redmine API client

4221.1M24](/packages/kbsali-redmine-api)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

963.1M35](/packages/getbrevo-brevo-php)[swisnl/json-api-client

A PHP package for mapping remote JSON:API resources to Eloquent like models and collections.

211473.2k12](/packages/swisnl-json-api-client)[smsapi/php-client

SMSAPI API PHP Client

652.1M17](/packages/smsapi-php-client)[wordpress/php-ai-client

A provider agnostic PHP AI client SDK to communicate with any generative AI models of various capabilities using a uniform API.

26236.6k14](/packages/wordpress-php-ai-client)[smsapi.pl/php-client

SMSAPI API PHP Client

6581.4k1](/packages/smsapipl-php-client)

PHPackages © 2026

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