Skip to content

games:import-stats

Imports statistics JSON data for a specific game version.

Overview

This command imports pre-generated statistics from JSON files into the database for a specific game version. It's typically used to import analysis results from external processing or to restore statistics data.

Usage

php artisan games:import-stats [options]

Options

--game-id=ID
ID of the specific game to process.
--game-name=NAME
Name of the game to process (only used if game-id is not provided).
--version-id=ID
Game version ID in the database.
--stats-file=PATH
Path to the stats JSON file to import.

JSON Format

The stats JSON file should contain structured data with the following format:

{
  "characters": [
    {
      "name": "Character Name",
      "blocks": 150,
      "words": 2500,
      "language": "en"
    }
  ],
  "metadata": {
    "total_blocks": 500,
    "total_words": 8000,
    "languages": ["en", "ja"]
  }
}

Examples

php artisan games:import-stats --game-id=123 --stats-file=/path/to/stats.json

Imports stats for the latest version of game ID 123.

php artisan games:import-stats --game-name="My Game" --stats-file=stats.json

Imports stats for the latest version of the named game.

php artisan games:import-stats --version-id=456 --stats-file=./data/stats.json

Imports stats for a specific version ID.

php artisan games:import-stats --game-id=123 --stats-file=storage/stats/game123.json

Uses a relative path to the stats file.

When to Use

Recommended Usage Scenarios

  1. Importing analysis results from external tools
  2. Restoring statistics after data corruption
  3. Bulk importing pre-calculated statistics
  4. Migrating statistics from other systems
  5. Testing with known good statistics data

Validation

The command performs comprehensive validation:

File Validation

  • File Existence: Verifies the stats file exists and is readable
  • JSON Syntax: Validates proper JSON formatting
  • Schema Validation: Ensures required fields are present

Data Validation

  • Character Data: Validates character names and statistics
  • Numeric Values: Ensures blocks and words are non-negative integers
  • Language Codes: Validates language identifiers
  • Consistency: Checks totals match individual character sums

Import Process

Step Action Validation
1. File Loading Read and parse JSON file File exists, valid JSON
2. Target Resolution Identify game/version Game/version exists
3. Data Validation Validate statistics data Schema compliance
4. Database Update Import statistics Data integrity

Data Integrity

Import operations maintain data integrity through:

  • Transaction Wrapping: All-or-nothing import process
  • Backup Validation: Optionally preserve existing data
  • Consistency Checks: Verify totals and relationships
  • Duplicate Prevention: Handle existing statistics appropriately

Note: The import process will overwrite existing statistics for the specified version. Ensure you have backups if needed.