PHPackages                             simbiat/lodestone-parser - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. simbiat/lodestone-parser

ActiveLibrary[Parsing & Serialization](/categories/parsing)

simbiat/lodestone-parser
========================

FFXIV Lodestone parser in PHP

2.0.0+20250413(1y ago)081[1 issues](https://github.com/Simbiat/lodestone-parser/issues)AGPL-3.0-or-laterPHPPHP ^8.3

Since Mar 11Pushed 2w ago1 watchersCompare

[ Source](https://github.com/Simbiat/lodestone-parser)[ Packagist](https://packagist.org/packages/simbiat/lodestone-parser)[ Docs](https://github.com/Simbiat/lodestone-parser)[ RSS](/packages/simbiat-lodestone-parser/feed)WikiDiscussions main Synced 5d ago

READMEChangelog (10)DependenciesVersions (35)Used By (0)

Final Fantasy XIV: Lodestone PHP Parser
=======================================

[](#final-fantasy-xiv-lodestone-php-parser)

This project is PHP library for parsing data directly from the FFXIV Lodestone website initially based on one developed by [@viion](https://github.com/viion), but now completely rewritten. Previously was its [branch](https://github.com/Simbiat/lodestone-php).

The goal is to provide an extremely fast and lightweight library, it is built with the purpose of parsing as many characters as possible, key being: low memory, and micro-timed parsing methods.

Notes
-----

[](#notes)

- This library parses the live Lodestone website. This website is based in Tokyo.
- This library is built in PHP 8 minimum, please use the latest as this can increase

What's different?
-----------------

[](#whats-different)

This is what's different from original library from [@viion](https://github.com/viion):

- It has different code structure, that aims at reduction of rarely used or unnecessary functions and some standardization.
- Using regex instead of full HTML parsing for extra speed (and arrays instead of objects as result). It does not mean, that this will always be faster than using Symphony-based functions but will be true on average.
- More filters for your search queries.
- Return more potentially useful information where possible.
- Attempt at multilingual support. Some filters even support actual "names" used on Lodestone (instead of just IDs).
- Ability to "link" different types of entities, requesting several pages in one object. For example, you can get **both** Free Company and its members' details in same object.

Settings
--------

[](#settings)

It's possible to set your own UserAgent used by CURL: simply use `->setUserAgent('user_agent')`

It's also possible to change LodeStone language by `->setLanguage('na')`. Accepted language values are `na`, `eu`, `jp`, `fr`, `de`

It's possible to utilize Benchmarking to get parsing times for each iteration by `->setBenchmark(true)`

Error handling
--------------

[](#error-handling)

In the new concept fatal errors generally can happen only during HTTP requests. In order not to break "linking" function, they are handled softly in the code itself and are reported to `->errors` and `->last_error` arrays. In essence, when an error occurs you will simply get an empty result for specific entity, and it will not be added to output.

To get last error you can use `->getLastError($close)`. For list of all errors - `-getErrors($close)`. `$close` is an expected boolean, that, if set to `true`, will close the cURL handle. It is set to `false` by default, based on assumption, that you are using these only for some kind of validation.

All pages
---------

[](#all-pages)

All parsers accepting `page` number support value of `0`, which will return all pages (that is run the respective parser recursively). Default value for `page` is set to `1` to limit resources used.

Test script
-----------

[](#test-script)

There is a `\Simbiat\FFXIV\LodestoneTest` class to test run all the available functions in some general scenarios. Run it to get samples of output formatting and timings for each type of test in a table format. Note, that the last 2 tests are 'error tests', so their results are purposefully reversed for the report's consistency. Additionally, achievements' test is purposefully ran with `details` set to true and Free Company members in `All pages` mode, because of this their benchmark results will be presented as list of timings.

Getting results
---------------

[](#getting-results)

To get results of parsers (listed below) you need to run `->getResult($close)`, which will return the array with the results. `$close` is an expected boolean, that, if set to `true`, will close the cURL handle. It is set to `true` by default, based on assumption, that getting results will be your last action.

**NOTICE**: if you are not calling `->getResult($close)` at all or are calling it only with `false`, it's recommended to explicitly unset the object you are using, unless you are using to free up resources.

Parsers
-------

[](#parsers)

  Function Parameters (in required order) Return key Description   Characters   `getCharacter` `$id` - id of character. `characters[$character]`, where `$character` is id of character returned with respective details as an array. Returns character details.   `getCharacterJobs` `$id` - id of character. `characters[$id]['jobs']`, where `$id` is id of character. Returns character jobs' details.   `getCharacterFriends` - `$id` - id of character.
- `int $page = 1` - characters' page. Defaults to `1`.

 `characters[$id]['friends'][$character]`, where `$id` is id of character and `$character` is id of friends returned with respective details as an array. Returns character's friends.   `getCharacterFollowing` - `$id` - id of character.
- `int $page = 1` - characters' page. Defaults to `1`.

 `characters[$id]['followed'][$character]`, where `$id` is id of character and `$character` is id of followed characters returned with respective details as an array. Returns characters followed by selected one.   `getCharacterAchievements` - `$id` - id of character.
- `$achievement_id = false` - id of achievement. Required if you want to search for specific achievement.
- `$kind = 1` - category of achievement. Acts as subcategory if `$category` is `true`. Multilingual. If `0` is sent all categories will be retrieved.
- `bool $category = false` - switch to turn `$kind` into subcategory.
- `bool $details = false` - switch to grab details for all achievements in category. Be careful, since this will increase runtimes proportionally to amount of achievements.
- `bool $only_owned = false` - flag to return only owned achievements. Returns everything by default.

 `characters[$character]['achievements'][$achievement]`, where `$character` is id of character and `$achievement` is id of achievement returned with respective details as an array. Returns character's achievements, if they are public.   Groups   `getFreeCompany` `$id` - id of Free Company. `freecompanies[$freecompany]`, where `$freecompany` is id of Free Company returned with respective details as an array. Returns information about Free Company without members.   `getFreeCompanyMembers` - `$id` - id of Free Company.
- `int $page = 1` - members' page. Defaults to `1`

 `freecompanies[$freecompany][$character]`, where `$freecompany` is id of Free Company and `$character` is id of each member returned with respective details as an array. Returns requested members' page of the Free Company.   `getLinkshell` - `$id` - id of Linkshell (numeric) or Crossworld Linkshell (alfa-numeric).
- `int $page = 1` - members' page. Defaults to `1`

 `linkshells[$linkshell]`, where `$linkshell` is id of linkshell returned with respective details as an array. Returns requested member's page of the Linkshell and general information.   `getPvPTeam` `$id` - id of PvP Team. `pvpteams[$pvpteam]`, where `$pvpteam` is id of PvP Team returned with respective details as an array. Returns general information and members of PvP Team.   Ranking   `getFeast` - `int $season = 1` - number of season to get results for. Defaults to `1`.
- `string $dc_group = ''` - server name to filter. Defaults to empty string, meaning no filtering.
- `string $rank_type = 'all'` - type of rank to filter. Defaults to `all`, meaning no filtering. Multilingual.

 `feast[$season][$character]`, where `$season` is the value passed at call and `$character` is id of each character returned with respective details as an array. Returns The Feasts rankings for requested season, server and/or rank.   `getDeepDungeon` - `int $id = 1` - id of Deep Dungeon as per Lodestone. 1 stands for 'Palace of the Dead', 2 stands for 'Heaven-on-High'. Defaults to `1`.
- `string $dc_group = ''` - server name to filter. Defaults to empty string, meaning no filtering.
- `string $solo_party = 'party'` - 'party' or 'solo' rankings to get. Defaults to `party`, same as Lodestone.
- `string $subtype = 'PLD'` - job to filter. Used only if `$solo_party` is set to `solo`. Expects common 3-letter abbreviations and defaults to `PLD`, same as Lodestone.

 `deep_dungeon[$id]['party'][$character]` or `deep_dungeon[$id]['solo'][$subtype][$character]`, where `$id` is id of the dungeon, `$subtype` is common 3-letter abbreviation of the respective job and `$character` is id of each character returned with respective details as an array. Returns ranking of respective Deep Dungeon.   `getFrontline` - `string $week_month = 'weekly'` - type of ranking. Defaults to `'weekly'`.
- `int $week = 0` - number of week (YYYYNN format) or month (YYYYMM format). Defaults to `0`, that is current week or month.
- `string $dc_group = ''` - data center name to filter. Defaults to empty string, meaning no filtering.
- `string $worldname = ''` - server name to filter. Defaults to empty string, meaning no filtering.
- `int $pvp_rank = 0` - minimum PvP rank to filter. Defaults to `0`, meaning no filtering.
- `int $match = 0` - minimum number of matches to filter. Defaults to `0`, meaning no filtering.
- `string $gc_id = ''` - Grand Company to filter. Defaults to empty string, meaning no filtering. Multilingual
- `string $sort = 'win'` - sorting order. Accepts `'win'` (sort by number of won matches), `'match'` (sort by total number of matches) and `'rate'` (sort by winning rate). Defaults to `'win'`.

 `frontline['weekly'][$week][$character]` or `frontline['monthly'][$month][$character]`, where `$week` and `$month` is identification of request week or month and `$character` is id of each character returned with respective details as an array. Returns Frontline rankings for selected period.   `getGrandCompanyRanking` - `string $week_month = 'weekly'` - type of ranking. Defaults to `'weekly'`.
- `int $week = 0` - number of week (YYYYNN format) or month (YYYYMM format). Defaults to `0`, that is current week or month.
- `string $worldname = ''` - server name to filter. Defaults to empty string, meaning no filtering.
- `string $gc_id = ''` - Grand Company to filter. Defaults to empty string, meaning no filtering. Multilingual
- `int $page = 1` - number of the page to parse. Defaults to `1`.

 `grand_company_ranking['weekly'][$week][$character]` or `grand_company_ranking['monthly'][$month][$character]`, where `$week` and `$month` is identification of request week or month and `$character` is id of each character returned with respective details as an array. Returns Grand Company rankings for selected period.   `getFreeCompanyRanking` - `string $week_month = 'weekly'` - type of ranking. Defaults to `'weekly'`.
- `int $week = 0` - number of week (YYYYNN format) or month (YYYYMM format). Defaults to `0`, that is current week or month.
- `string $worldname = ''` - server name to filter. Defaults to empty string, meaning no filtering.
- `string $gc_id = ''` - Free Company to filter. Defaults to empty string, meaning no filtering. Multilingual
- `int $page = 1` - number of the page to parse. Defaults to `1`.

 `free_company_ranking['weekly'][$week][$character]` or `free_company_ranking['monthly'][$month][$character]`, where `$week` and `$month` is identification of request week or month and `$character` is id of each character returned with respective details as an array. Returns Free Company rankings for selected period.   Search   `searchCharacter` - `string $name = ''` - optional name to search.
- `string $server = ''` - optional server name to filter.
- `string $class_job = ''` - optional filter by class/job. Supports types of jobs and common 3-letter abbreviations.
- `string $race_tribe = ''` - optional filter by tribe/clan. Multilingual.
- `$gc_id = ''` - optional filter by Grand Company affiliation. Accepts singular string or an array of such. Multilingual.
- `string|array $blog_lang = ''` - optional filter by character language. Accepts same variables as for language setting. Accepts singular string or an array of such.
- `string $order = ''` - optional sorting order. Refer to Converters.php for possible values.
- `int $page = 1` - number of the page to parse. Defaults to `1`.

 `characters[$character]`, where `$character` is id of each character returned with respective details as an array. Returns array for entities from respective search function with array keys being respective entity's id on Lodestone.   `searchFreeCompany` - `string $name = ''` - optional name to search.
- `string $server = ''` - optional server name to filter.
- `int $character_count = 0` - filter by Free Company size. Supports same counts as Lodestone: 1-10, 11-30, 31-50, 51-. Anything else will result in no filtering.
- `string|array $activities = ''` - optional filter by Company activities. Accepts singular string or an array of such. Multilingual.
- `string|array $roles = ''` - optional filter by seeking roles. Accepts singular string or an array of such. Multilingual.
- `string $active_time = ''` - optional filter by active time. Multilingual.
- `string $join = ''` - optional filter by recruitment status. Multilingual.
- `string $house = ''` - optional filter by estate availability. Multilingual.
- `$gc_id = ''` - optional filter by Grand Company affiliation. Accepts singular string or an array of such. Multilingual.
- `string $order = ''` - optional sorting order. Refer to Converters.php for possible values.
- `int $page = 1` - number of the page to parse. Defaults to `1`.

 `freecompanies[$freecompany]`, where `$freecompany` is id of each Free Company returned with respective details as an array.   `searchLinkshell` - `string $name = ''` - optional name to search.
- `string $server = ''` - optional server name to filter.
- `int $character_count = 0` - filter by Linkshell size. Supports same counts as Lodestone: 1-10, 11-30, 31-50, 51-. Anything else will result in no filtering.
- `string $order = ''` - optional sorting order. Refer to Converters.php for possible values.
- `int $page = 1` - number of the page to parse. Defaults to `1`.
- `bool $crossworld = false` - whether we are searching for regular or crossworld Linkshell. Searching for regular ones by default.

 `linkshells[$linkshell]`, where `$linkshell` is id of each linkshell returned with respective details as an array.   `searchPvPTeam` - `string $name = ''` - optional name to search.
- `string $server = ''` - optional server name to filter.
- `string $order = ''` - optional sorting order. Refer to Converters.php for possible values.
- `int $page = 1` - number of the page to parse. Defaults to `1`.

 `pvpteams[$pvpteam]`, where `$pvpteam` is id of each PvP Team returned with respective details as an array.   Database   `searchDatabase` - `string $type` - mandatory type of entity to search for on Lodestone taken from `https://eu.finalfantasyxiv.com/lodestone/playguide/db/$type`.
- `int $category = 0` - optional ID of category taken from `https://eu.finalfantasyxiv.com/lodestone/playguide/db/achievement/?category2=$category`.
- `int $subcategory = 0` - optional ID of subcategory taken from `https://eu.finalfantasyxiv.com/lodestone/playguide/db/achievement/?category2=2&category3=$subcategory`. Will be ignored if category is not set.
- `string $search = ''` - optional string to search for.
- `int $page = 1` - number of the page to parse. Defaults to `1`.

 `database[$type][$entityid]`, where `$type` is type of entities searched, and `$entityid` is ID of the entity in the database returned with respective details as an array. Returns array for entities from respective search function with array keys being respective entity's id on Lodestone.   `getAchievementFromDB` `string $db_id` - database ID for achievement taken from `https://eu.finalfantasyxiv.com/lodestone/playguide/db/achievement/$db_id`. `database['achievement']['db_id']`, where `$db_id` is ID of the achievement in the database returned with respective details as an array. Returns achievement details. Result is equivalent to `getCharacterAchievements` when getting details for 1 achievement.   News   `getLodestoneNews`  `news` Returns news as seen on main page of Lodestone.   `getLodestoneTopics` `int $page=1` - number of the page to parse. Defaults to `1`. `topics` Return respective news subcategories.   `getLodestoneNotices` `notices`   `getLodestoneMaintenance` `maintenance`   `getLodestoneUpdates` `updates`   `getLodestoneStatus` `status`   Special   `getLodestoneBanners`  `banners` Returns banners from Lodestone.   `getWorldStatus` `bool $world_details=false` - whether to show detailed status of worlds or not. Defaults to `false`. `worlds` Returns alphabet sorted array with worlds (servers) names as array keys and status (online/offline) as values. In `detailed` mode shows online status, maintenance status, whether world is preferred or congested and whether world can have new characters as boolean values.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance75

Regular maintenance activity

Popularity9

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity79

Established project with proven stability

 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 ~45 days

Recently: every ~68 days

Total

34

Last Release

399d ago

Major Versions

1.2.1+20250209 → 2.0.0+202504132025-04-13

PHP version history (2 changes)1.0.0+20210311PHP ^8

1.1.9+202400409PHP ^8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6022665?v=4)[Dmitrii Kustov](/maintainers/Simbiat)[@Simbiat](https://github.com/Simbiat)

---

Top Contributors

[![Simbiat](https://avatars.githubusercontent.com/u/6022665?v=4)](https://github.com/Simbiat "Simbiat (21 commits)")

---

Tags

phpparserffxivlodestone

### Embed Badge

![Health badge](/badges/simbiat-lodestone-parser/health.svg)

```
[![Health](https://phpackages.com/badges/simbiat-lodestone-parser/health.svg)](https://phpackages.com/packages/simbiat-lodestone-parser)
```

###  Alternatives

[doctrine/lexer

PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.

11.2k910.8M118](/packages/doctrine-lexer)[simplehtmldom/simplehtmldom

A fast, simple and reliable HTML document parser for PHP.

1921.3M14](/packages/simplehtmldom-simplehtmldom)[corveda/php-sandbox

A PHP library that can be used to run PHP code in a sandboxed environment

23483.5k2](/packages/corveda-php-sandbox)[romanpitak/nginx-config-processor

Nginx configuration files processor.

7235.3k1](/packages/romanpitak-nginx-config-processor)[sbsaga/toon

🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts & LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON).

6115.6k](/packages/sbsaga-toon)[leonelquinteros/php-toml

PHP parser for TOML language ( https://github.com/toml-lang/toml )

266.7k](/packages/leonelquinteros-php-toml)

PHPackages © 2026

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