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(6mo ago)02821MITPHPPHP ^8.3CI passing

Since Dec 8Pushed 6mo 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 today

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

37

—

LowBetter than 81% of packages

Maintenance66

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

202d ago

Major Versions

v1.0.0 → v2.0.02025-12-09

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/246080545?v=4)[izaghar](/maintainers/izaghar)[@izaghar](https://github.com/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

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60216.0M83](/packages/mollie-mollie-api-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

1003.9M50](/packages/getbrevo-brevo-php)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6942.5M421](/packages/drupal-core-recommended)[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)

PHPackages © 2026

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