PHPackages                             mistralys/x4-core - 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. [Database & ORM](/categories/database)
4. /
5. mistralys/x4-core

ActiveLibrary[Database & ORM](/categories/database)

mistralys/x4-core
=================

Database and utility classes used to access X4: Foundations game data in an OOP way.

1.4.0(3w ago)0157MITPHPPHP >=8.4

Since May 23Pushed 3w ago1 watchersCompare

[ Source](https://github.com/Mistralys/x4-core)[ Packagist](https://packagist.org/packages/mistralys/x4-core)[ RSS](/packages/mistralys-x4-core/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (24)Versions (19)Used By (0)

X4 Database Core
================

[](#x4-database-core)

Database and utility classes used to access X4: Foundations game data in an OOP way. It is designed to be used as a dependency in other projects (see [X4 Tools](#x4-tools-and-libraries), for example).

Version
-------

[](#version)

**Current Version:** 1.0.1 **Documentation:** [Project Manifest](docs/agents/project-manifest/README.md)

Database features
-----------------

[](#database-features)

- Faction database
- Ware database
- Ship database
- Station module database
- Blueprint database
- Translation tool
- DLC metadata
- Macro file index
- Automated database file generation from the game data

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

[](#requirements)

- PHP 8.4 or higher.
- [Composer](https://getcomposer.org/).

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

[](#installation)

Require the package in your Composer project:

```
composer require mistralys/x4-core
```

Usage
-----

[](#usage)

### Raw JSON data files

[](#raw-json-data-files)

All extracted game data is stored in JSON files in the `data` folder.

- [factions.json](./data/factions.json) - Faction definitions
- [wares.json](./data/wares.json) - Ware definitions
- [ships.json](./data/ships.json) - Ship definitions
- [modules.json](./data/modules.json) - Station module definitions
- [blueprints.json](./data/blueprints.json) - Blueprints
- [macro-index.json](./data/macro-index.json) - Macro file index
- [data-sources.json](./data/data-sources.json) - Data sources (DLC metadata)

### The faction classes

[](#the-faction-classes)

All factions available in the game can be accessed through the faction collection.

#### The faction collection

[](#the-faction-collection)

All factions are available through the `FactionDefs` collection class.

```
use Mistralys\X4\Database\Factions\FactionDefs;

echo "Available factions:" . PHP_EOL;

foreach(FactionDefs::getInstance()->getAll() as $faction) {
    echo $faction->getLabel() . PHP_EOL;
}
```

#### Faction getter methods

[](#faction-getter-methods)

When working with the faction classes, dedicated getter methods exist to access factions instead of using the faction ID constants.

```
use Mistralys\X4\Database\Factions\KnownFactions;

$argon = KnownFactions::getInstance()->getArgon();

echo $argon->getLabel(); // Outputs "Argon"
```

### The ware classes

[](#the-ware-classes)

All items available in the game, from trade goods to ships, are available in the main ware collection.

#### The ware collection

[](#the-ware-collection)

All wares are available through the `Wares` collection class.

```
use Mistralys\X4\Database\Wares\WareDefs;

echo "Available wares:" . PHP_EOL;

foreach(WareDefs::getInstance()->getAll() as $ware) {
    echo $ware->getLabel() . PHP_EOL;
}
```

This fetches wares by ID:

```
use Mistralys\X4\Database\Wares\WareDefs;

$advancedElectronics = WareDefs::getInstance()
    ->getByID('module_gen_prod_advancedelectronics_01');
```

#### The ware finder

[](#the-ware-finder)

The ware finder utility class allows selecting search criteria to filter the wares and retrieve specific wares. The following example uses the ware finder to retrieve all ship engines provided by the Boron DLC.

```
use Mistralys\X4\Database\Wares\WareDefs;
use Mistralys\X4\Database\Wares\WareGroups;
use Mistralys\X4\Database\DataSources\KnownDataSources;

$boronEngines = WareDefs::getInstance()
    ->findWares()
    ->selectDataSource(KnownDataSources::DATA_SOURCE_KINGDOM_END)
    ->selectGroup(WareGroups::GROUP_ENGINES)
    ->getAll();
```

### The ship classes

[](#the-ship-classes)

All ships available in the game can be accessed through the ship collection.

```
use Mistralys\X4\Database\Ships\ShipDefs;

echo "Available ships:" . PHP_EOL;

foreach(ShipDefs::getInstance()->getAll() as $ship) {
    echo $ship->getLabel() . PHP_EOL;
}
```

### Accessing translations

[](#accessing-translations)

The official translations are bundled with the package, and can be accessed to translate text codes like `{20101,20604}` ("Manorina (Gas) Vanguard").

```
use Mistralys\X4\Database\Translations\Languages;

$english = Languages::getInstance()->getEnglish();

$shipName = $english->t('{20101,20604}');
```

Development setup
-----------------

[](#development-setup)

### Unpacking game data files

[](#unpacking-game-data-files)

The mod requires the game's data files to be unpacked using the [X4 Data Extractor](https://github.com/Mistralys/x4-data-extractor) tool. The tool acts as a library to access the extracted information. This includes the DLC metadata necessary to generate the correct mod file structure.

Please refer to the tool's instructions to unpack the game data files.

### Configuration

[](#configuration)

1. Unpack the data files (see above).
2. Clone this repository.
3. Copy `dev-config.php.dist` to `dev-config.php`.
4. Edit the file to set the correct paths.

### Database update

[](#database-update)

To update the bundled database, use the `build` Composer command to update the JSON files in the `data` folder.

```
composer build
```

X4 Tools and libraries
----------------------

[](#x4-tools-and-libraries)

- [X4 Game Notes](https://github.com/Mistralys/x4-game-notes) - *Docs* - Howto, tips and general information about X4.
- [X4 Core](https://github.com/Mistralys/x4-core) - *Library* - Access X4 game data in an OOP way.
- [X4 Data Extractor](https://github.com/Mistralys/x4-data-extractor) - *Tool & Library* - Extract X4 game files.
- [X4 Savegame Parser](https://github.com/Mistralys/x4-savegame-parser) - *Tool* - Parse X4 savegames to extract information.
- [X4 Cargo Size Mod](https://github.com/Mistralys/x4-mod-cargo-sizes) - *Mod* - Mod to increase ship cargo sizes.

###  Health Score

50

↑

FairBetter than 95% of packages

Maintenance95

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity71

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

Total

18

Last Release

21d ago

Major Versions

0.0.11 → 1.0.02025-07-04

PHP version history (3 changes)0.0.1PHP ^7.4

0.0.7PHP >=7.4

1.1.0PHP >=8.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8895528?v=4)[Mistralys](/maintainers/Mistralys)[@Mistralys](https://github.com/Mistralys)

---

Top Contributors

[![Mistralys](https://avatars.githubusercontent.com/u/8895528?v=4)](https://github.com/Mistralys "Mistralys (422 commits)")

---

Tags

game-datalibraryx4foundations

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mistralys-x4-core/health.svg)

```
[![Health](https://phpackages.com/badges/mistralys-x4-core/health.svg)](https://phpackages.com/packages/mistralys-x4-core)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M3.1k](/packages/craftcms-cms)[jason-munro/cypht

Lightweight Open Source webmail written in PHP and JavaScript

1.6k157.9k](/packages/jason-munro-cypht)[drupal/core-dev

require-dev dependencies from drupal/drupal; use in addition to drupal/core-recommended to run tests from drupal/core.

2022.6M343](/packages/drupal-core-dev)[mapbender/mapbender

Mapbender library

10418.3k8](/packages/mapbender-mapbender)[chameleon-system/chameleon-base

The Chameleon System core.

1028.6k5](/packages/chameleon-system-chameleon-base)[sproutcms/cms

Enterprise content management and framework

242.5k4](/packages/sproutcms-cms)

PHPackages © 2026

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